# 10 部署与运维

## 1. 目标环境（当前服务器）
- Ubuntu 22.04.5 LTS，systemd 249，12 核 / 30GB 内存
- Node 22.15、Python 3.10
- `claude`（`~/.local/bin/claude`）、`codex` 0.154.0（`~/.local/bin/codex`），均由本人在终端登录
- unprivileged user namespace 已开启，`bwrap` 可正常运行（已验证）

## 2. 依赖安装状态（2026-10-22 已完成）

| 依赖 | 状态 | 用途 |
|---|---|---|
| bubblewrap | ✅ 已有 | 两个引擎的沙箱 |
| socat | ✅ 新装 | Claude 沙箱网络代理 |
| ripgrep | ✅ 新装 | 资料检索、Codex 搜索 |
| pandoc | ✅ 新装（2.9） | docx 读取与转换 |
| fonts-noto-cjk | ✅ 新装 | 中文图表、PDF |
| LibreOffice、poppler-utils | ✅ 已有 | Office 转换、公式重算、PDF 渲染 |
| `/srv/agent-server/{data,workspaces,knowledge,skills,runtime,logs}` | ✅ 已创建（属主 jerry-remote，0750） | 服务数据目录 |
| Python venv `/srv/agent-server/runtime/py` | ✅ 已创建 | pandas 2.3、numpy、pyarrow、duckdb 1.5、matplotlib 3.10、seaborn、plotly、openpyxl、xlsxwriter、python-docx、python-pptx、pypdf、pdfplumber、reportlab、markitdown |
| `/srv/agent-server/runtime/requirements.lock` | ✅ | 锁定的 Python 依赖版本，用于重建环境 |
| `/srv/agent-server/runtime/matplotlibrc` | ✅ 已验证中文渲染 | 默认字体为 Noto Sans CJK |
| Node 依赖（docx 等） | ⏳ M1 | 随项目 `package.json` 安装 |
| 官方技能（xlsx/docx/pdf/pptx） | ⏳ M1 | 核对许可证后放入 `skills/` |

重建 Python 环境：
```bash
python3 -m venv /srv/agent-server/runtime/py
/srv/agent-server/runtime/py/bin/pip install -r /srv/agent-server/runtime/requirements.lock
```

## 3. 运行方式
- **开发期**：在项目目录直接 `pnpm dev` 运行，不经过 systemd，用于快速迭代。
- **常驻运行**：使用 systemd 系统服务，`User=jerry-remote`，加固配置见 06 §5.1。构建产物部署到 `/srv/agent-server/app`（因为 ProtectHome 会隐藏 home 下的项目目录）。

## 4. 对外访问
- AgentServer 只监听 `127.0.0.1:8787`
- 前面放 Caddy 或 Nginx 做 HTTPS 和反向代理；需要为 SSE 关闭缓冲（Nginx 用 `proxy_buffering off`，并加大读超时）
- 只在内网或 VPN（如 Tailscale）中开放

## 5. 运维
- 日志：pino JSON 输出到 journald；`journalctl -u agent-server`
- 备份：每天对 `data/agent.db` 做 SQLite 在线备份；CLI 登录态不备份
- 健康检查：`GET /healthz`（进程存活）、`GET /readyz`（数据库、两个 CLI 的登录状态、app-server 进程、Codex 个人插件是否已禁用的自检结果）
- 登录过期：后台"引擎状态"页和状态栏显示红色徽标；在终端重新登录即可，服务不需要重启
- 升级：见 03 §5
- 定时任务（进程内）：工作区清理、用量日汇总、引擎健康检查（每 10 分钟）、资料库可见性复检