SRxing151/deepseek-harness-deploy

deepseek-harness-deploy

DeepSeek Harness（类 Claude Code 的开源 Agent 框架）的 Docker 部署与多用户隔离工具包。

上游框架目前没有官方 Docker 部署方案，且其 Web 服务是单用户架构：无账号体系、凭据全局共享、Agent 以同一 OS 身份执行代码。本工具包解决两件事：

1. 部署：一份 Dockerfile + Nginx 网关配置，把框架跑进容器并安全地暴露到内网/公网；
2. 多用户隔离：一人一容器（Silo 模型）——独立数据卷、独立凭据、独立 Basic Auth 账号，用户之间会话与 API Key 物理隔离。

架构

用户浏览器                    Nginx 网关 (dsh-nginx)                dsh 容器实例
┌─────────┐  HTTPS+BasicAuth ┌─────────────────────┐            ┌───────────────────────┐
│  alice  │────────────────▶ │ :48080 只认 alice    │───────────▶│ dsh-alice  DSH_PORT=3080
└─────────┘                  │                      │            │  ├ 卷 dsh-alice-data（会话/凭据）
┌─────────┐                  │ :48081 只认 bob      │            │  └ /workspace-alice（宿主目录）
│   bob   │────────────────▶ │                      │──────┐     └───────────────────────┘
└─────────┘                  └─────────────────────┘      │     ┌───────────────────────┐
TLS 终止 + WebSocket 透传    └────▶│ dsh-bob    DSH_PORT=3081
│  ├ 卷 dsh-bob-data
│  └ /workspace-bob
└───────────────────────┘

为什么需要 Nginx 网关：dsh web 出于安全设计只监听 127.0.0.1（上游拒绝 --host 0.0.0.0），必须由宿主上的反向代理终止 TLS 并对外暴露。网关配置里有两个容易踩坑的关键点（模板已内置并注释）：

- 普通路由必须 proxy_set_header Host $http_host（保留端口）；
- /api/ 路由必须把 Host 伪装为本机并清空 Origin，否则服务端信任域校验会导致所有 API 403。

快速开始

在 Linux 服务器上（Docker 已安装并运行）：

git clone https://github.com/SRxing151/deepseek-harness-deploy.git
cd deepseek-harness-deploy

1. 构建镜像（克隆上游源码并构建；可复现构建建议锁定上游版本）
DSH_UPSTREAM_REF=0.1.0-rc.5 ./scripts/build-image.sh
已有本地源码则: ./scripts/build-image.sh /path/to/deepseek-harness

2. 初始化网关：部署目录 + 自签证书 + Nginx 容器（root 执行，只需一次）
sudo ./scripts/init.sh

3. 添加用户（交互式输入密码）
sudo ./scripts/add-user.sh alice 48080

4. 浏览器访问
https://:48080/   账号 alice + 你设置的密码（自签证书点「高级→继续前往」）

添加第二个用户：

sudo ./scripts/add-user.sh bob 48081
bob 登录后会话列表为空（独立数据卷），需在设置里配自己的 API Key

验证隔离（alice 的凭据在 bob 的端口必须 401）
./scripts/verify-isolation.sh alice: bob:

详细文档：docs/deployment.md（部署与镜像迁移）、docs/multi-user.md（多用户原理）、docs/security.md（安全模型与攻击面分析）。

可配置项（环境变量）

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| DSH_IMAGE | deepseek-harness:local | 镜像名 |
| DSH_SERVER_IP | hostname -I 第一个地址 | 写入 DSH_TRUSTED_HOST 的对外 IP；多网卡时务必显式指定 |
| DSH_PROJECTS_ROOT | /srv/dsh-projects | 每个用户的宿主机项目根目录（$ROOT/） |
| DSH_DEPLOY_DIR | /etc/dsh-deploy | 部署文件根目录（证书/密码/Nginx 配置） |
| DSH_UPSTREAM | 上游 GitHub 地址 | build-image.sh 克隆的源 |

安全模型（务必阅读）

本方案提供的是容器级隔离，不是完整的多租户系统：

- dsh 的文件沙箱只限制写（workspace-write 模式下锁工作区 + 临时目录，bash 走 Landlock 内核级沙箱），读不受限——Agent 能读容器内可见的一切文件；
- 容器以 root 运行、--network host 共享宿主网络栈；
- 因此真正的对外安全边界是 Nginx 的 TLS + Basic Auth + 网络层（内网/VPN/防火墙），请只挂载必要目录、使用强密码；
- 多用户场景下，一人一容器正是为了把“读不受限 + prompt injection”的攻击面限制在单用户自己的容器内。

完整分析（含跨用户凭据窃取的攻击推演与缓解）：docs/security.md。

已知限制

- 每实例常驻内存数百 MB 且闲置不释放——用户规模到几十人时建议进入 Roadmap 的编排方案；
- 自签证书（生产建议换 Let's Encrypt）；
- verify-isolation.sh 的密码会进入 shell 历史，验证后建议清理；
- SELinux 环境下挂载可能需要 :Z 标签。

Roadmap

- [ ] Let's Encrypt 正式证书 + 自动续期
- [ ] 容器非 root 化
- [ ] bridge 网络替代 host 网络
- [ ] Kubernetes Operator（登录拉起、闲置回收、滚动升级）
- [ ] 结构化日志与实例级资源限额模板

反馈

欢迎通过 Issue / Discussion 提出改进，特别希望听到：

- Nginx 配置的加固建议（限流、fail2ban、真实 IP 透传）
- 脚本在不同发行版（CentOS / Ubuntu / openEuler / 麒麟）上的兼容性问题
- K8s 编排方向的实现思路
- 安全模型评审
- 其他任何对该项目的意见

致谢与许可

- 上游框架：deepseek-ai/deepseek-harness（MIT）
- 本工具包以 MIT 许可发布，见 LICENSE