跳到主要内容

部署与运维

环境要求​

  • Python 3.11+
  • Windows、macOS 或 Linux

安装​

git clone https://github.com/countbot-ai/countbot.git
cd countbot
pip install -r requirements.txt

国内网络可使用镜像:

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

启动​

生产模式​

python start_app.py

默认监听 127.0.0.1:8000，启动后自动打开浏览器。

监听外部访问​

如需从其他设备访问:

$env:COUNTBOT_HOST = '0.0.0.0'
$env:COUNTBOT_PORT = '8000'
python start_app.py
export COUNTBOT_HOST=0.0.0.0
export COUNTBOT_PORT=8000
python start_app.py

启动后会打印:

  • Local: http://localhost:8000 — 本机访问
  • Network: http://<局域网IP>:8000 — 局域网访问

开发模式​

uvicorn backend.app:app --reload --host 0.0.0.0 --port 8000

桌面模式​

python start_desktop.py

使用 pywebview 打开原生窗口,后端在同一进程启动,窗口关闭时自动退出。

::: warning 桌面预编译版限制 桌面预编译版（如 .exe 安装包）不支持通过环境变量修改监听地址，无法开启远程访问模式。

如需远程访问，请使用源码版本 (python start_app.py)。 :::

环境变量​

变量默认值说明
COUNTBOT_HOST127.0.0.1监听地址
COUNTBOT_PORT8000监听端口
BRAVE_API_KEY—Brave Search API 密钥(可选)

大部分配置(模型、人格、安全、渠道等)通过 Web UI 管理,存储在 SQLite 数据库中。

启动流程​

python start_app.py
  │
  ├─ 1. 初始化日志系统
  ├─ 2. 读取 COUNTBOT_HOST / COUNTBOT_PORT
  ├─ 3. 打印访问地址(Local + Network)
  ├─ 4. 延迟 15 秒后自动打开浏览器
  └─ 5. 启动 uvicorn 服务器

后端 lifespan:
  │
  ├─ 1. 初始化数据库 (data/countbot.db)
  ├─ 2. 从数据库加载配置
  ├─ 3. 创建共享组件 (Provider、Memory、Skills、Tools 等)
  ├─ 4. 初始化消息队列与限流器
  ├─ 5. 初始化渠道管理器
  ├─ 6. 后台启动渠道连接
  ├─ 7. 启动消息处理器
  ├─ 8. 初始化 Cron 调度器
  └─ 9. 注册心跳任务

数据库​

存储位置: data/countbot.db

表说明
sessions聊天会话
messages聊天消息
settings配置键值对
cron_jobs定时任务
tasks后台任务
tool_conversations工具调用记录

备份:

cp data/countbot.db data/countbot.db.bak

生产部署​

Linux systemd​

# /etc/systemd/system/countbot.service
[Unit]
Description=CountBot AI Assistant
After=network.target

[Service]
Type=simple
User=countbot
WorkingDirectory=/opt/countbot
ExecStart=/opt/countbot/venv/bin/python start_app.py
Restart=always
RestartSec=5
Environment=COUNTBOT_HOST=0.0.0.0
Environment=COUNTBOT_PORT=8000

[Install]
WantedBy=multi-user.target
sudo systemctl enable countbot
sudo systemctl start countbot

Docker​

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "start_app.py"]
docker build -t countbot .
docker run -d -p 8000:8000 -v ./data:/app/data countbot

Nginx 反向代理​

server {
    listen 80;
    server_name countbot.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
    }
}

WebSocket 需要 Upgrade 和 Connection 头。

注意: 通过反向代理访问时,CountBot 会检测 X-Forwarded-For 头,不会视为本地请求,需要正常登录认证。

远程访问认证​

通过非本地 IP 访问时,系统自动启用认证:

  • 首次设置管理员账号只能在服务所在机器本地完成,或通过 /setup/<随机码> 远程初始化
  • 密码要求: 至少 8 位,包含大写字母、小写字母和数字
  • 登录态通过 Cookie CountBot_token 维持
  • 本地访问(127.0.0.1)不受影响
  • 渠道消息(微信/飞书/钉钉等)不受影响

详见远程访问认证。

目录结构​

countbot/
├── data/                  # 运行时数据
│   ├── countbot.db        # SQLite 数据库
│   └── audit_logs/        # 审计日志
├── workspace/             # 工作空间(可配置)
│   ├── skills/            # 技能目录
│   ├── memory/            # 记忆文件
│   └── temp/              # 临时文件
└── frontend/dist/         # 前端构建产物

日志​

使用 loguru 记录,输出到 stderr:

  • DEBUG — 工具定义、消息构建
  • INFO — 启动、工具执行、会话
  • WARNING — 可选功能不可用
  • ERROR — 工具执行失败、渠道连接失败

故障排查​

端口被占用​

OSError: [Errno 48] Address already in use

修改端口:

$env:COUNTBOT_PORT = '8001'
python start_app.py

数据库锁定​

sqlite3.OperationalError: database is locked

确保只有一个 CountBot 实例在运行。

渠道 SDK 缺失​

ImportError: No module named 'dingtalk_stream'

安装对应 SDK:

pip install dingtalk-stream  # 钉钉
pip install qq-botpy         # QQ
pip install lark-oapi        # 飞书

不需要某个渠道可以不安装对应 SDK,系统会自动跳过。

相关文件​

文件说明
start_app.py应用入口(浏览器模式)
start_desktop.py桌面应用入口(pywebview)
backend/app.pyFastAPI 应用和生命周期
backend/database.py数据库配置
backend/utils/runtime_env.py环境变量处理
requirements.txtPython 依赖