docs: add complete Chinese documentation

2026-07-26 21:32:12 +08:00
parent 66109235e2
commit e2e7a7ba37
24 changed files with 1251 additions and 14 deletions
@@ -0,0 +1,106 @@
+# 运维手册
+
+中文 · [English](operations.md)
+
+## 生产布局
+
+- 公开地址：`https://agent.k1412.top`
+- 公开文档：`https://agent.k1412.top/doc/`
+- NAS 项目：`/boot/config/plugins/compose.manager/projects/k1412-agent`
+- 公开主机端口：`12004`
+- 执行提供方：`ssh-docker`
+- 执行主机 Docker root：`/srv/k1412-data/docker`
+- Runtime 模型 API 路由：`http://172.31.0.1:3000`（从 `k1412-agent_egress` 网络访问 NAS 主机网关，绕过公网代理）
+- 执行主机工作区数据卷：名为 `k1412-ws-data-<hashed-user-id>` 的 Docker volume
+
+本文和仓库中都不应存放任何凭据。
+
+## 部署
+
+构建并推送不可变的 `linux/amd64` 镜像：
+
+```bash
+docker buildx build --platform linux/amd64 -f docker/web.Dockerfile \
+  -t docker.k1412.top/wuyang/k1412-agent-web:<release> --push .
+docker buildx build --platform linux/amd64 -f docker/runtime.Dockerfile \
+  -t docker.k1412.top/wuyang/k1412-agent-runtime:<release> --push .
+docker buildx build --platform linux/amd64 -f docker/gateway.Dockerfile \
+  -t docker.k1412.top/wuyang/k1412-agent-gateway:<release> --push .
+docker buildx build --platform linux/amd64 -f docker/workspace.Dockerfile \
+  -t docker.k1412.top/wuyang/k1412-agent-workspace:<release> --push .
+```
+
+把 `deploy/docker-compose.yml`、`deploy/docker-compose.override.yml` 和 `deploy/docker-compose.ssh.yml` 复制到 NAS 项目。只修改受保护 `.env` 中的不可变镜像标签和非敏感设置，使用 `docker compose config` 校验，然后拉取并重建服务。
+
+NAS 部署中的 `MODEL_API_BASE_URL` 应设置为上面列出的内部模型 API 路由。`https://api.k1412.top` 仍是外部 API 入口，但 Runtime 不应让耗时较长的 Agent 推理经过公网反向代理。
+
+设置 `DEEPSEEK_API_BASE_URL=https://api.deepseek.com`，并且只把 `DEEPSEEK_API_KEY` 放在受保护的部署 `.env` 中。这个密钥只由 Runtime 调用 DeepSeek V4 Pro 使用，绝不能加入浏览器、Compose 文件、镜像、仓库或日志。
+
+SSH override 会从 Gateway 中移除 `/var/run/docker.sock`，并把专用 SSH 目录只读挂载到 `/root/.ssh`。
+
+文档门户复制到现有 Web 镜像的 `/app/build/doc`。它和 Open WebUI 使用相同的主机端口与代理路由，因此不需要额外的 Compose 项目、NAS 端口、DNS 记录或 Nginx Proxy Manager 主机。
+
+Workspace 镜像把用户 home、软件包缓存和 Python user base 放在 `/workspace/.agent` 下；约定的项目虚拟环境是 `/workspace/.venv`。将 `WORKSPACE_IMAGE` 更新为新的不可变标签后，Gateway 会在每个过期工作区下次被访问时替换其容器，同时保留用户的命名数据卷。
+
+## Ollama 模型常驻
+
+NAS Ollama 服务通过以下配置让 Luna、Terra 和 Sol 保持常驻：
+
+- `OLLAMA_KEEP_ALIVE=-1`；
+- `OLLAMA_MAX_LOADED_MODELS=3`；
+- `OLLAMA_NUM_PARALLEL=1`；
+- `OLLAMA_GPU_OVERHEAD=2147483648`；
+- 启用 Flash Attention 和 `q8_0` KV cache。
+
+三个 32K 上下文 runner 的实测 GPU 分配量分别约为 2.88 GB、4.12 GB 和 18.44 GB，合计约 25.44 GB，占用 32 GB GPU。除非重新进行同时加载测试并为推理开销预留容量，否则不要增加上下文长度或单模型并行度。
+
+持久化 Unraid 模板位于 `/boot/config/plugins/dockerMan/templates-user/my-ollama.xml`。`/boot/config/plugins/dynamix/k1412-ollama.cron` 中有一个带锁、幂等的五分钟检查任务，在主机或容器重启后只预热缺失的模型。恢复后应确认 `/api/ps` 列出全部三个模型，并且到期时间为无限。
+
+## 工作区迁移
+
+更换执行主机前：
+
+1. 停止 Gateway，阻止新的工作区写操作开始；
+2. 使用 `app.k1412.component=user-workspace` 标签/名称前缀枚举容器和数据卷；
+3. 停止每个工作区容器；
+4. 将每个命名数据卷以 tar 流传输到新 Docker 主机上名称完全相同的数据卷；
+5. 在新主机拉取精确的 Workspace 镜像；
+6. 使用新的 SSH 目标启动 Gateway；
+7. 对每个迁移后的数据卷验证文件列表和至少一次读取；
+8. 在验证窗口结束前保留旧数据卷。
+
+数据卷名称只包含用户 ID 哈希，不包含邮箱或显示名称。
+
+## 验证
+
+每个版本都要执行：
+
+```bash
+.venv/bin/pytest
+RUN_DOCKER_INTEGRATION=1 .venv/bin/pytest tests/test_docker_workspace.py
+./scripts/verify-e2e.sh
+./scripts/audit-images.sh
+```
+
+生产冒烟检查必须覆盖：
+
+- 匿名请求被重定向或拒绝；
+- 已批准用户只能看到精确的四个 Agent 模型；
+- 每个模型都经过自定义 Agent 循环；
+- Agent 创建并验证一个真实文件；
+- 文件浏览器能列出并下载该文件；
+- 第二个用户无法看到它；
+- Gateway 健康检查报告 `ssh-docker`；
+- 工作区容器存在于物理执行主机，而不是 NAS。
+
+## 备份优先级
+
+依次备份：
+
+1. PostgreSQL；
+2. Open WebUI 数据卷；
+3. PostgreSQL 中的 Runtime 状态；
+4. 执行主机上的每用户工作区数据卷；
+5. 通过私有基础设施备份流程保存受保护的部署 `.env` 与 SSH 目录。
+
+Redis 是可以重建的协调状态，优先级低于数据库和工作区数据卷。