wuyang
107 lines
5.1 KiB
Markdown
107 lines
5.1 KiB
Markdown
# 运维手册
|
||
|
||
中文 · [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 是可以重建的协调状态，优先级低于数据库和工作区数据卷。
|