部署指南 / Deployment Guide

August 31, 2026 · View on GitHub

本插件的 HTTP 适配服务可以部署为：

Windows 本机服务（PowerShell 一键脚本）
Docker 容器（推荐给 Linux 服务器 / 云主机）
Linux 裸进程 + systemd（无需 Docker 的轻量方案）

三种方式跑的都是同一个 deepseek-plugin-runner 服务（模块路径 deepseek_multi_agent_plugin.adapters.http），对外暴露 /health、/agents、 /status、/run、/runs、/history、/sessions、/register 等端点（完整列表与角色要求见 HTTP 服务接口）。

R8 安全默认值： loopback（127.0.0.1 / ::1 / localhost）可在没有鉴权的情况下运行；任何非 loopback 监听地址都必须配置 --token / --role / DS_AGENT_ROLES，否则服务拒绝启动。仅在明确的可信私有网络场景中，才能使用 --allow-insecure-remote 显式关闭这一保护。

1. Windows 本机部署

仓库根目录的 deploy/ 提供了三个脚本：

cd C:\path\to\deepseek-multi-agent-plugin
.\deploy\install.ps1          # 创建 venv、安装包、跑测试
.\deploy\start_server.ps1 -Port 8000
.\deploy\stop_server.ps1

start_server.ps1 的行为：

自动从 ~/.dsh/.credentials.yaml 或环境变量 DEEPSEEK_API_KEY 读取 API Key；
自动生成 / 复用 32 位鉴权 token，保存在 %LOCALAPPDATA%\deepseek-multi-agent-plugin\token.txt；
后台隐藏窗口启动服务，PID 写入仓库根目录 .server.pid；
默认只监听 127.0.0.1；需要局域网访问时用 -HostBind 0.0.0.0，并确保传递鉴权 token。

验证：

$token = (Get-Content "$env:LOCALAPPDATA\deepseek-multi-agent-plugin\token.txt" -Raw).Trim()
Invoke-RestMethod -Uri http://127.0.0.1:8000/health -Headers @{ Authorization = "Bearer $token" }

1.2 开机自启（Windows 任务计划程序）

把服务注册为开机启动任务（以当前用户身份运行，开机时启动、系统重启后自动拉起）：

schtasks /Create /TN "DeepSeekMultiAgent" /SC ONSTART /RU $env:USERNAME /RL LIMITED `
  /TR "powershell -NoProfile -ExecutionPolicy Bypass -File C:\path\to\deepseek-multi-agent-plugin\deploy\start_server.ps1"

如需手动停止任务：

schtasks /End /TN "DeepSeekMultiAgent"

2. Docker 部署

仓库自带 Dockerfile 与 docker-compose.yml。

2.1 准备 API Key

export DEEPSEEK_API_KEY=sk-xxxxxx
export DS_AGENT_TOKEN=$(openssl rand -hex 16)   # 对外监听时必需

2.2 环境变量

变量	默认值	说明
`HOST`	`0.0.0.0`	容器内监听地址；这是非 loopback 地址，因此必须配置 token/RBAC
`PORT`	`8000`	容器内监听端口
`CONFIG`	`/app/example_config.yaml`	YAML/JSON agent 配置路径
`DEEPSEEK_API_KEY`	无	DeepSeek API Key（LLM Agent 必需）
`DS_AGENT_TOKEN`	无	Bearer 鉴权 token；`HOST=0.0.0.0` 时必须设置
`DS_AGENT_ROLES`	无	JSON RBAC，例如 `{"readonly":"ro-token","admin":"admin-token"}`

2.3 启动

docker compose up -d --build
docker compose ps

服务会监听宿主机 8000 端口。因为容器默认监听 0.0.0.0，启动前必须提供 DS_AGENT_TOKEN 或 DS_AGENT_ROLES；未提供时服务会 fail-closed 并拒绝启动。

2.4 健康检查与日志

docker compose ps                 # STATUS 应为 healthy
docker compose logs -f deepseek-multi-agent
curl -s http://127.0.0.1:8000/health \
  -H "Authorization: Bearer $DS_AGENT_TOKEN"

2.5 优雅停止 / 更新

docker compose stop                 # 发送 SIGTERM，服务优雅关闭
docker compose down                 # 停止并删除容器
docker compose up -d --build         # 更新镜像后重启
docker compose ps

容器收到 SIGTERM 后会停止接收新请求、等待正在执行的任务返回，再关闭 HTTP 服务（stop_grace_period 默认 15 秒，可调整）。

Dockerfile 内置了 HEALTHCHECK（用 Python 标准库 urllib 请求 /health）， docker compose ps 的 STATUS 会显示 healthy / unhealthy。

3. Linux 裸进程 + systemd

不需要 Docker 时，可以用 venv + systemd 常驻：

python3 -m venv /opt/deepseek-multi-agent/.venv
/opt/deepseek-multi-agent/.venv/bin/pip install -e ".[dev]"

创建 /etc/systemd/system/deepseek-multi-agent.service：

[Unit]
Description=DeepSeek Multi-Agent Plugin HTTP Adapter
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/deepseek-multi-agent
EnvironmentFile=/etc/deepseek-multi-agent.env
ExecStart=/opt/deepseek-multi-agent/.venv/bin/deepseek-plugin-runner \
    --host 127.0.0.1 --port 8000 \
    --config /opt/deepseek-multi-agent/example_config.yaml
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
RestartSec=3
TimeoutStopSec=20

[Install]
WantedBy=multi-user.target

/etc/deepseek-multi-agent.env 内容示例：

DEEPSEEK_API_KEY=sk-xxxxxx
DS_AGENT_TOKEN=your-generated-token

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable --now deepseek-multi-agent
sudo systemctl status deepseek-multi-agent

如果 systemd 单元改为监听 0.0.0.0 或其他远程地址，必须保留 DS_AGENT_TOKEN 或 DS_AGENT_ROLES；否则 R8 安全门禁会在服务启动阶段拒绝绑定。

4. 安全建议

服务自带 Bearer 令牌鉴权：单令牌（DS_AGENT_TOKEN / --token，等于 admin 角色）或分角色令牌（DS_AGENT_ROLES 传 JSON 对象 {role: token}，或重复 --role ROLE:TOKEN）；
角色层级 readonly < user < operator < admin，端点按最低角色鉴权（见 HTTP 服务接口第 2 节）；
服务默认对非 loopback HTTP 监听地址 fail-closed；生产公网/局域网部署应配置鉴权，不要依赖 --allow-insecure-remote；
--allow-insecure-remote 仅用于明确可信的私有网络、测试网或已由外层网络 ACL 完整保护的场景；
服务本身不提供 TLS，公网部署务必放在反向代理（Nginx / Caddy）后面；
监听地址默认 127.0.0.1，跨机调用时再开放远程地址；
只要服务对外可访问，就必须配置令牌鉴权（Authorization: Bearer <token>）；
DEEPSEEK_API_KEY 通过环境变量或密钥管理注入，不要写进镜像 / 仓库；
长期运行的服务建议设置 --session-ttl 与 --max-sessions，防止会话内存增长；
生产环境建议用独立配置文件挂载，不要修改镜像内的默认配置。

5. 常见问题

Q: Docker 容器一启动就退出？

如果容器使用默认 HOST=0.0.0.0，首先检查是否提供了 DS_AGENT_TOKEN 或 DS_AGENT_ROLES。 R8 会在无鉴权的远程监听场景直接拒绝启动，这是预期行为。

Q: 调用 /run 返回 401？

请求头缺少 Authorization: Bearer <token>，或 token 与启动时不一致。

Q: systemd 启动后立刻退出？

用 journalctl -u deepseek-multi-agent -e 看日志；如果把 --host 配成了非 loopback 地址，确认同时设置了 DS_AGENT_TOKEN / DS_AGENT_ROLES。