AgentServer/docs/design/10-deployment.md

10 部署与运维

1. 目标环境

• Ubuntu 22.04.5 LTS，systemd 249，12 核 / 30GB 内存，Node 22.15（/usr/local/bin/node）
• 服务以专用用户 agentsvc 运行（ADR-0012），使用 Agent SDK 自带的 Claude Code 二进制

2. 目录与权限

/srv/agent-server/            root 0755
├─ app/server/                root，只读：服务端（pnpm deploy 产物，含 SDK 自带的 claude）
├─ app/admin/                 root，只读：后台静态资源
├─ runtime/                   root，只读：py/（venv）、node/node_modules、matplotlibrc
├─ skills/                    root，只读：本地技能（来自仓库 skills/）
├─ home/                      agentsvc 0700：Claude Code 登录态与插件（~/.claude）
├─ data/                      agentsvc 0700：agent.db
├─ workspaces/                agentsvc 0700：会话工作区
├─ logs/                      agentsvc 0700
└─ knowledge/                 agentsvc:agentsvc 2770：默认资料库位置（管理员在 agentsvc 组中，可以直接放文件）

3. 脚本（deploy/）

脚本	用途	何时执行
sudo deploy/install.sh	创建 agentsvc、目录与权限、安装 systemd unit 和 agent-claude 命令	首次安装；修改 unit 后
sudo deploy/setup-runtime.sh	安装系统工具、Python venv（deploy/runtime/requirements.txt）、Node 包（deploy/runtime/package.json）、字体配置	首次安装；依赖变化后
deploy/deploy.sh	构建 → pnpm deploy → rsync 到 app/、同步 skills/ → 重启服务 → 健康检查	每次发布
agent-claude ...	以 agentsvc 身份运行自带的 Claude Code	登录（/login）、查看状态（auth status）、手动管理插件

首次安装顺序：sudo deploy/install.sh → sudo deploy/setup-runtime.sh → deploy/deploy.sh → 在后台"概览"页登录 Claude（或执行 agent-claude auth login）。

4. systemd 加固（deploy/agent-server.service）

• 监听 0.0.0.0:8787：局域网可直接访问（HTTP 明文）；公网经反向代理访问
• 反向代理：https://agent.zenpower.cc（代理服务器 47.236.165.115，经 VPN 隧道以 100.96.0.2 连入），在代理上终止 HTTPS，HTTP 自动跳转 HTTPS
  • AGENT_SERVER_TRUST_PROXY=100.96.0.2：只信任这个地址的 X-Forwarded-*，服务记录真实客户端 IP，登录限流按真实 IP 生效
  • 已验证（2026-10-23）：SSE 不缓冲（心跳按时到达）、20 MB 上传正常
  • 代理的隧道地址变化时，需要同步修改 unit 中的 AGENT_SERVER_TRUST_PROXY
• User=agentsvc；ProtectSystem=strict + 只有 home/data/managed-skills/workspaces/logs/knowledge 可写；ProtectHome=yes；PrivateTmp=yes；UMask=0077
• NoNewPrivileges=yes；InaccessiblePaths= docker.sock 与 LXD socket（纵深防御，agentsvc 本身也没有权限）
• 不能开启 RestrictNamespaces（bubblewrap 需要）
• 资源：MemoryMax=8G、CPUQuota=600%、TasksMax=1024
• 资料库放在 /srv/agent-server/knowledge 以外时，需要在 unit 中追加 ReadOnlyPaths=（或在可写资料库中追加 ReadWritePaths=）并重启；home 下的路径对服务不可见

5. 开发环境

• pnpm dev:server：以本人身份运行，端口 8788，数据在仓库 .dev-data/，使用本人的 ~/.claude 登录态
• pnpm dev:admin：http://127.0.0.1:5173/admin/，代理到 8788
• runtime 和 skills 与正式服务共用（只读）

6. 运维

• 日志：journalctl -u agent-server -f
• 状态：systemctl status agent-server；健康检查 GET /healthz、GET /readyz
• 登录 / 登录过期：在后台"概览"页点"登录"完成（ADR-0014），或在终端执行 agent-claude auth login，无需重启
• 备份：每天对 data/agent.db 做 SQLite 在线备份；home/ 中的登录态可以不备份（重新登录即可）
• 升级 Claude Code：升级 @anthropic-ai/claude-agent-sdk 依赖后执行 deploy.sh（自带 CLI 版本随之更新），再在 Playground 回归验证