1 line
5.9 KiB
JSON
1 line
5.9 KiB
JSON
{"repo": "chenlinzhe/tiangongzituan-muti-agent", "files": {"docs/DEPLOY.md": {"7bae166272d3bd1e581b2aaa0548b6e6649ee442": {"t": 1785746602.730004, "n": 4734, "h": "ef967c4a0e46f692", "c": "# 部署指南\n\n> 适合企业内网或公网生产环境。包含 **Docker / systemd / pm2** 三种部署方式 + nginx 反代 + 备份 + 监控。\n\n## 0. 前置准备\n\n- Linux (Ubuntu 22.04+/Debian 12+/CentOS 9+ Stream)\n- 公网域名 + SSL 证书（推荐 Let's Encrypt）\n- LLM Provider API Key（DeepSeek/OpenAI/Moonshot/通义/自建任选）\n- 服务器 ≥ 2C 4G（含 LLM 调用并发余量）\n\n## 1. 三种部署方式 (任选一)\n\n### A. Docker Compose（推荐，最简单）\n\n```bash\ngit clone --recurse-submodules https://your.git/demo2.git\ncd demo2\ncp .env.example .env\n# 编辑 .env: 填 DEEPSEEK_API_KEY / API_KEY / GATEWAY_TOKEN / ALLOWED_ORIGINS=https://demo2.example.com\n\ndocker compose -f deploy/docker-compose.prod.yml up -d --build\n```\n\n容器自动包含：\n- backend（uvicorn :8001）\n- frontend（nginx 反代 + 静态资源 :9528→80）\n- backup（每日 03:00 自动备份 DB）\n\n### B. systemd（适合裸机 / VPS）\n\n```bash\n# 1. 用户 + 目录\nsudo useradd -r -s /usr/sbin/nologin demo2\nsudo mkdir -p /opt/demo2 /opt/demo2/logs\nsudo chown -R demo2:demo2 /opt/demo2\n\n# 2. 部署代码\nsudo -u demo2 git clone https://your.git/demo2.git /opt/demo2\ncd /opt/demo2\nsudo -u demo2 python3 -m venv .venv\nsudo -u demo2 .venv/bin/pip install -r backend/requirements.txt\nsudo -u demo2 cp .env.example .env\nsudo -u demo2 vi .env # 填 key\n\n# 3. 装 systemd unit\nsudo cp deploy/systemd/demo2-backend.service /etc/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable --now demo2-backend\nsudo systemctl status demo2-backend\n\n# 4. 装前端 (静态文件)\ncd /opt/demo2/frontend\nsudo -u demo2 npm ci && sudo -u demo2 npm run build\n\n# 5. nginx 前面挡\nsudo cp /opt/demo2/deploy/nginx.demo2.conf /etc/nginx/sites-available/demo2\nsudo ln -s /etc/nginx/sites-available/demo2 /etc/nginx/sites-enabled/\nsudo nginx -t && sudo systemctl reload nginx\n\n# 6. SSL (Let's Encrypt)\nsudo certbot --nginx -d demo2.example.com\n\n# 7. 定期备份\necho \"0 3 * * * cd /opt/demo2 && /opt/demo2/.venv/bin/python scripts/backup_db.py\" | sudo -u demo2 crontab -\n```\n\n### C. pm2（Node 风格进程管理，适合熟 PM2 的团队）\n\n```bash\nsudo npm i -g pm2\n\ncd /opt/demo2\n.venv/bin/pip install -r backend/requirements.txt\n\ncat > ecosystem.config.cjs <<'EOF'\nmodule.exports = {\n apps: [{\n name: \"demo2-backend\",\n interpreter: \"/opt/demo2/.venv/bin/python\",\n script: \"-m\",\n args: \"uvicorn app.main:app --host 127.0.0.1 --port 8001 --app-dir backend --workers 2\",\n cwd: \"/opt/demo2\",\n env_file: \"/opt/demo2/.env\",\n max_memory_restart: \"1G\",\n autorestart: true\n }]\n}\nEOF\npm2 start ecosystem.config.cjs\npm2 save && pm2 startup\n```\n\n## 2. 必配 `.env`\n\n```bash\n# LLM\nLLM_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-real-key\n\n# 安全\nAPI_KEY=use-a-strong-random-32-char-string-here # 留空 = 关闭鉴权(只内网用)\nGATEWAY_TOKEN=another-strong-random # OpenClaw WS 网关\nALLOWED_ORIGINS=https://demo2.example.com # CORS,生产必须配具体域名\n\n# 编排限制 (按用量调)\nMAX_ROUNDS=12\nMAX_TOOL_CALLS_PER_TURN=3\nMAX_HISTORY_CHARS=8000\n\n# 备份保留天数\nBACKUP_KEEP_DAYS=14\n```\n\n## 3. 监控\n\n- **健康检查**: `curl https://demo2.example.com/api/health`\n 返回 `{\"ok\":true,\"db\":true,\"llm\":{...},\"auth_enabled\":true}` 才算健康\n- **24h 指标**: `curl -H \"X-API-Key: $API_KEY\" https://.../api/metrics`\n 含调用次数 / token 用量 / p95 延迟 / 按 op 分类\n- **审计日志**: SQLite 表 `audit_logs`，每次 chat/instantiate/create_role 都有记录\n\n接 Prometheus / Loki：\n- nginx `access.log` → 用 promtail 推 Loki\n- `/health` 给 blackbox_exporter\n- `/metrics` 写一个 exporter 把字段转成 Prometheus 格式（待做）\n\n## 4. 备份与恢复\n\n**自动备份**: cron 调 `scripts/backup_db.py`，保留 14 天，SQLite online backup API 不锁主库。\n\n**手动备份**:\n```bash\ncd /opt/demo2 && .venv/bin/python scripts/backup_db.py\n# → backend/data/backups/wecom-YYYYMMDD-HHMMSS.db\n```\n\n**恢复**:\n```bash\nsudo systemctl stop demo2-backend\ncp backend/data/backups/wecom-20260519-030000.db backend/data/wecom.db\nsudo systemctl start demo2-backend\n```\n\n## 5. 升级\n\n```bash\ncd /opt/demo2\nsudo -u demo2 git pull\nsudo -u demo2 .venv/bin/pip install -r backend/requirements.txt\n# 启动时自动 ALTER TABLE 兼容旧 schema (见 main.py 启动钩子)\nsudo systemctl restart demo2-backend\n\n# 前端\ncd frontend\nsudo -u demo2 npm ci && sudo -u demo2 npm run build\n# nginx 直接挑新 dist\n```\n\n## 6. 安全要点 (生产 checklist)\n\n- [x] `API_KEY` 设强随机（≥32 字符）\n- [x] `GATEWAY_TOKEN` 同上\n- [x] `ALLOWED_ORIGINS` 设具体域名，不要 `*`\n- [x] nginx 强制 HTTPS（HSTS）\n- [x] systemd unit 启用 `NoNewPrivileges` + `ProtectSystem=strict`\n- [x] DB 文件权限 600\n- [ ] LLM 密钥用 Vault / AWS Secrets Manager（暂未集成，可手工注入 env）\n- [ ] 多用户场景需补加 user-scoping（路线图 P2-4）\n\n## 7. 故障排查\n\n| 症状 | 排查 |\n|------|------|\n| `/health` 返回 `ok:false` | 看 `db` / `llm.key_set` 哪个是 false |\n| 群聊不流式 / 卡顿 | nginx 是否 `proxy_buffering off`；timeout 是否 ≥10min |\n| 401 unauthorized | 浏览器请求是否带 `X-API-Key` header |\n| backend 启不来 | `journalctl -u demo2-backend -e -n 200` |\n| LLM 报错 | `/metrics` `by_op` 看是否大量 success=false；查 `audit_logs.meta` |\n| DB 锁 | 看是否有长事务；备份脚本用 online backup 不该出现 |\n\n## 8. 进一步阅读\n\n- 架构: [`DESIGN.md`](DESIGN.md)\n- 场景: [`SCENARIOS.md`](SCENARIOS.md)\n- 路线图: [`PROJECT_PLAN.md`](PROJECT_PLAN.md)\n"}}}} |