首页 / 文档 / 团队版 / 服务器部署（团队版）

服务器部署（团队版）

从零部署一套属于自己团队的通千算智：目录规约、systemd、nginx、HTTPS 与门户

本页给运维同学：在一台干净的 Linux 服务器上部署团队版（宿主 Agent + 团队门户 + 域名 + HTTPS）。

只想自己用，直接用桌面客户端最省事；想给别人也开账号，再按本文部署团队版。

0. 目录规约（先定，后患最少）

用途	路径	备注
程序源码	`/root/通千算智`（或 `/opt/tqsz`）	只放代码，不放数据
站点/数据盘	`/www/wwwroot/<域名>/`	有数据盘时优先放这里
门户数据	`/root/portal/portal.db`	账号与审计
工作空间	`/root/cow`（`agent_workspace`）	记忆、知识库、产出
日志	交给 systemd（`journalctl -u`）	别自己写 nohup.out 后忘了轮转

先建目录规约再部署：如果服务器加过数据盘，务必把工作空间、门户数据、站点目录都放到数据盘上，否则根盘迟早写满。

1. 环境准备

bash

# Python（3.7 ~ 3.13，推荐 3.9；不建议 3.13 做桌面打包，但服务器运行没问题）
python3 -V

# 依赖
cd /opt && git clone <你的代码仓库> tqsz && cd tqsz
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-optional.txt   # 可选，含浏览器工具等
pip install -e .                           # 安装 cow CLI（推荐）

注意

SQLite 版本会影响中文记忆检索：记忆索引使用 FTS5 的 trigram 分词器，需要 SQLite ≥ 3.34。部分系统（如 Alibaba Cloud Linux 3）自带 3.26，会静默降级为 LIKE 模糊匹配（只在日志里留一行 WARNING）。升级方式二选一：升级系统 sqlite，或安装 pysqlite3-binary 并在 sitecustomize 中替换 sqlite3 模块。

2. 配置

bash

cp config-template.json config.json

团队部署至少要改这几项：

json

{
  "channel_type": "web",
  "web_host": "127.0.0.1",
  "web_port": 9899,
  "web_password": "<强密码>",
  "agent": true,
  "agent_workspace": "/root/cow",
  "self_evolution_enabled": true,
  "speech_recognition": false
}

保持 web_host 为 127.0.0.1，让 nginx 反代到它——这样 9899 永远不暴露在公网。

3. systemd 托管

ini

# /etc/systemd/system/tqsz.service
[Unit]
Description=TongQianSuanZhi Agent
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/tqsz
ExecStart=/opt/tqsz/venv/bin/python app.py
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1
# 中文记忆检索需新版 SQLite 时：
# Environment=PYTHONPATH=/root/cow_patch

[Install]
WantedBy=multi-user.target

bash

systemctl daemon-reload && systemctl enable --now tqsz
systemctl status tqsz && journalctl -u tqsz -f

4. 反向代理与 HTTPS

nginx

server {
    listen 80;
    server_name tqsz.example.com;
    location /.well-known/acme-challenge/ { root /www/wwwroot/_acme_tqsz; }
    location / { return 301 https://$host$request_uri; }
}

server {
    listen 443 ssl http2;
    server_name tqsz.example.com;

    ssl_certificate     /path/fullchain.pem;
    ssl_certificate_key /path/privkey.key;

    client_max_body_size 32m;          # 上传文件/语音

    location / {
        proxy_pass http://127.0.0.1:9899;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # 流式输出/WebSocket 必须放行
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 600s;
        proxy_buffering off;
    }
}

发证书（任选 acme.sh / 面板 / certbot）：

bash

acme.sh --issue -d tqsz.example.com --webroot /www/wwwroot/_acme_tqsz
acme.sh --install-cert -d tqsz.example.com \
  --key-file /path/privkey.key --fullchain-file /path/fullchain.pem \
  --reloadcmd "nginx -s reload"

注意

HTTPS 不是可选项：浏览器的麦克风（语音输入）、剪贴板、摄像头 API 只允许在安全上下文（HTTPS 或 localhost）下使用。没有 HTTPS 时，「点麦克风没反应」往往就是这个原因。

5. 团队门户（多用户）

宿主本身是单用户设计。团队版在它前面加一层门户服务实现多成员：

代码

浏览器 → nginx ┬ /portal/ → 门户服务（FastAPI，监听 127.0.0.1:8011）  注册/登录/管理后台
               └ /        → 宿主（127.0.0.1:9899），经 auth_request 校验门户会话

nginx

location /portal/ {
    proxy_pass http://127.0.0.1:8011;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

location = /portal/api/check {          # 子请求鉴权
    proxy_pass http://127.0.0.1:8011/api/check;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
}

location / {
    auth_request /portal/api/check;
    error_page 401 = @to_portal;
    proxy_pass http://127.0.0.1:9899;
    # …其余同上
}

location @to_portal {
    return 302 /portal/;
}

ini

# /etc/systemd/system/tqsz-portal.service
[Unit]
Description=TongQianSuanZhi Portal
After=network.target

[Service]
Type=simple
WorkingDirectory=/root/portal
ExecStart=/root/portal/venv/bin/uvicorn app:app --host 127.0.0.1 --port 8011
Restart=always

[Install]
WantedBy=multi-user.target

为什么这么做：不改宿主源码，上游更新不会冲掉门户；成员空间隔离复用宿主原有的多 Agent 能力。

验证顺序很重要：先确认 curl http://127.0.0.1:8011/ 通（门户自己在跑），再确认 nginx 的 /portal/ 能打开，最后验证未登录访问 / 会被 302 到门户。一次只验证一层，出问题时才知道坏在哪一层。

6. 上线验收清单

[ ] curl -I https://域名/ 返回 302（未登录跳门户）或 200
[ ] 注册一个测试成员 → 能看到只属于自己的对话
[ ] 该成员访问知识库 → 与已有内容一致（共享生效）
[ ] 管理员后台能看到该成员与登录审计
[ ] 重启服务器后服务自动拉起（systemctl is-enabled）
[ ] 备份脚本跑过一次，且实际恢复验证过