# 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）
- `User=agentsvc`；`ProtectSystem=strict` + 只有 home/data/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 回归验证