wuyang/zk-data-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
zk-data-agent/docs/operations.zh-CN.md
T
wuyang e2e7a7ba37 docs: add complete Chinese documentation
2026-07-26 21:32:12 +08:00

5.1 KiB
Raw Permalink Blame History

运维手册

中文 · English

生产布局

  • 公开地址：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 镜像：

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 哈希，不包含邮箱或显示名称。

验证

每个版本都要执行：

.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 是可以重建的协调状态，优先级低于数据库和工作区数据卷。

Reference in New Issue View Git Blame Copy Permalink