Skip to content
Back to search

deepseek-harness-docker

Deploy, configure, verify, upgrade, and troubleshoot DeepSeek Harness with the community Docker, Docker Compose, rootless Podman, and Helm runtime, including the built-in Chromium/noVNC browser, optional protected LAN gateway, optional ungoogled-chromium image, and optional plugin market. Use when users ask to run DSH or DeepSeek Harness locally or on a trusted LAN or Kubernetes, mount a writable workspace, configure model credentials safely, enable the embedded browser, minimize browser background egress, choose the market image, or diagnose container health and startup problems.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/runzhliu--deepseek-harness-docker/badge.svg)](/listings/runzhliu--deepseek-harness-docker)

HTML

<a href="/listings/runzhliu--deepseek-harness-docker"><img src="/api/listings/runzhliu--deepseek-harness-docker/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 160 lines
  1. ---
  2. name: deepseek-harness-docker
  3. description: Deploy, configure, verify, upgrade, and troubleshoot DeepSeek Harness with the community Docker, Docker Compose, rootless Podman, and Helm runtime, including the built-in Chromium/noVNC browser, optional protected LAN gateway, optional ungoogled-chromium image, and optional plugin market. Use when users ask to run DSH or DeepSeek Harness locally or on a trusted LAN or Kubernetes, mount a writable workspace, configure model credentials safely, enable the embedded browser, minimize browser background egress, choose the market image, or diagnose container health and startup problems.
  4. ---
  5. # DeepSeek Harness Docker
  6. Use the public `runzhliu/deepseek-harness-docker` project as the source of truth. Treat it as a community containerization project around the official `@deepseek-ai/dsh` npm package, not as an official DeepSeek image.
  7. ## Preserve the security boundary
  8. - Bind native WebUI port `3080` and noVNC port `6080` to `127.0.0.1` only. For an explicit trusted-LAN request, use `compose.lan.yaml`; never publish the native ports.
  9. - Never create a public Ingress, LoadBalancer, NodePort, unrestricted `-p 3080:3080`, privileged container, or Docker socket mount.
  10. - Pass provider keys only at runtime through the Harness settings page, environment variables, `.env`, or Kubernetes Secrets. Never write credentials into Dockerfiles, images, Compose files committed to Git, logs, or answers.
  11. - Keep the named `dsh-home` volume unless the user explicitly asks to delete all Harness settings, credentials, sessions, and browser state.
  12. - Mount only the workspace the user authorizes. Do not broaden a bind mount to a home directory or filesystem root.
  13. - Treat the optional plugin market and every installed plugin as third-party code with access to the mounted workspace and persisted Harness profile.
  14. ## Locate the deployment files
  15. Use the current checkout when it contains `compose.yaml` and `Dockerfile`. Otherwise clone the public repository:
  16. ```bash
  17. git clone https://github.com/runzhliu/deepseek-harness-docker.git
  18. cd deepseek-harness-docker
  19. ```
  20. Read `README.md`, `SECURITY.md`, `compose.yaml`, and `.env.example` before changing defaults. Prefer the repository's pinned image and DSH versions; do not silently switch to `latest`.
  21. ## Choose the smallest suitable mode
  22. Use default Compose for a local, single-user WebUI with the embedded Debian Chromium desktop. The image attaches official Playwright MCP Browser Use to the same persistent Chromium used for visible human takeover. Add `compose.lan.yaml` only for an explicit trusted-LAN request, after choosing one exact bind address, an internal DNS name or IP, a Caddy Basic Auth credential, and a firewall boundary. This mode uses `caddy:2.11.4-alpine` and still represents one shared trust domain, not multi-tenancy. Select the immutable `0.2.2-rc.4-r1-ungoogled.1` tag only when the user explicitly prioritizes minimized Google background egress and accepts its contributor-binary and reduced browser-service tradeoffs. Add `compose.market.yaml` only when the user explicitly wants the community plugin market. Use headless mode for one-shot automation and Helm only when the user requests Kubernetes.
  23. Use `compose.bwrap.yaml` and immutable image `0.2.2-rc.4-r1-bwrap.1` only when a Docker host cannot enforce Landlock and the user accepts `seccomp=unconfined` plus `systempaths=unconfined`. First distinguish a kernel with Landlock omitted from the active LSM list from a kernel built without Landlock; prefer enabling the existing LSM when possible. Never add `SYS_ADMIN`, `--privileged`, or the Docker socket. Require unprivileged user namespaces, run `make bwrap-smoke`, and confirm `/workspace` writes succeed while writes to the test's separate outer writable mount fail. Do not apply this overlay to rootless Podman or Kubernetes.
  24. For an explicitly rootless Podman deployment, require Podman 4.5 and `podman-compose 1.6.0` or newer, then add `compose.podman.yaml`. Confirm `podman info --format '{{.Host.Security.Rootless}}'` returns `true`. The overlay maps the caller to container UID/GID 1000 and privately labels the workspace on SELinux hosts; authorize one dedicated project directory and never broaden the mount to a shared home or filesystem root. Use `make podman-smoke` when validation is requested.
  25. ## Enable protected LAN access
  26. Follow the `.env.lan.example` and README procedure. Generate the bcrypt hash without recording its plaintext, keep `.env.lan` private, bind `DSH_LAN_BIND_ADDRESS` to one exact server LAN IP, and prefer an internal DNS name for `DSH_LAN_HOST`. Start with `make lan-up`, install the persistent Caddy internal CA root on authorized clients, and use the DSH launch token only through the resulting HTTPS URL. Verify with `make lan-smoke`. Tell the user that all authenticated clients share the same Harness authority and that mutually untrusted users need isolated instances and volumes.
  27. ## Start the default local runtime
  28. 1. Confirm Docker and Compose are available:
  29. ```bash
  30. docker version
  31. docker compose version
  32. ```
  33. 2. Resolve the requested workspace to an absolute path and confirm it is the intended writable directory.
  34. 3. Pull and start without rebuilding unless the user asks for a local source build:
  35. ```bash
  36. DSH_WORKSPACE=/absolute/path/to/project docker compose pull
  37. DSH_WORKSPACE=/absolute/path/to/project docker compose up -d --no-build
  38. docker compose ps
  39. ```
  40. 4. Wait for the `deepseek-harness` service to become healthy. Verify both surfaces:
  41. ```bash
  42. test "$(curl --silent --output /dev/null --write-out '%{http_code}' http://127.0.0.1:3080/)" = 401
  43. curl --fail http://127.0.0.1:6080/novnc-debian-1.6.0-2/vnc.html
  44. docker compose logs --tail=120 deepseek-harness
  45. ```
  46. 5. Tell the user to open `http://127.0.0.1:3080`. Configure the model provider and key in Harness settings. Use the WebUI browser action for the embedded Chromium desktop; use `http://127.0.0.1:6080/novnc-debian-1.6.0-2/vnc.html?autoconnect=1` only as a direct fallback.
  47. ## Select the optional ungoogled browser
  48. Keep Debian Chromium as the default. For an explicit privacy-focused deployment, select the separate immutable image before pulling and starting:
  49. ```bash
  50. export DSH_IMAGE_VERSION=0.2.2-rc.4-r1-ungoogled.1
  51. DSH_WORKSPACE=/absolute/path/to/project docker compose pull
  52. DSH_WORKSPACE=/absolute/path/to/project docker compose up -d --no-build
  53. ```
  54. This image keeps its browser profile under `/home/node/.dsh/chrome-profile-ungoogled`. Do not point it at the default Chromium profile. Report that Safe Browsing, sync, push, Widevine, and Web Store integration may be absent or require manual setup. When validating the variant, inspect `/proc/net/tcp` and `/proc/net/tcp6` for remote port `146C` (hexadecimal 5228) and confirm `/tmp/dsh-desktop/chromium.log` has no `google_apis/gcm` entry.
  55. ## Enable the optional plugin market
  56. Keep the default image unchanged and opt in through the overlay:
  57. ```bash
  58. DSH_WORKSPACE=/absolute/path/to/project \
  59. docker compose -f compose.yaml -f compose.market.yaml pull
  60. DSH_WORKSPACE=/absolute/path/to/project \
  61. docker compose -f compose.yaml -f compose.market.yaml up -d --no-build
  62. docker compose -f compose.yaml -f compose.market.yaml ps
  63. ```
  64. If the market reports a pnpm store version mismatch, stop the service and run the repository's explicit repair command from `README.md`. Do not delete the profile or named volume as a shortcut.
  65. ## Run a headless task
  66. Use the pinned image and pass the provider key from the existing environment without printing it:
  67. ```bash
  68. docker run --rm \
  69. --env DEEPSEEK_API_KEY \
  70. --mount type=volume,src=dsh-home,dst=/home/node/.dsh \
  71. --mount type=bind,src=/absolute/path/to/project,dst=/workspace \
  72. runzhliu/deepseek-harness:0.2.2-rc.4-r1 \
  73. --profile headless "summarize this repository"
  74. ```
  75. From DSH `0.2.1-alpha.3`, Headless defaults to environment variables and `.env` without reading saved Web/Desktop keys. Supply the selected provider's runtime credentials explicitly. Replace the provider environment variable and model configuration only when the selected provider requires it. Keep secrets out of command output and shell history where possible.
  76. ## Deploy with Helm
  77. Use the included chart as a single-replica, stateful, private deployment:
  78. ```bash
  79. helm lint --strict charts/deepseek-harness
  80. helm upgrade --install deepseek-harness charts/deepseek-harness \
  81. --namespace deepseek-harness \
  82. --create-namespace
  83. kubectl -n deepseek-harness rollout status statefulset/deepseek-harness
  84. kubectl -n deepseek-harness port-forward service/deepseek-harness 3080:3080 6080:6080
  85. ```
  86. Use an existing Secret for provider credentials and an existing PVC when a persistent writable workspace is required. Preserve the chart's private Service and NetworkPolicy defaults.
  87. ## Build or upgrade safely
  88. - Run `make verify` before building changes.
  89. - Run `make build` and `make smoke` for the default image.
  90. - Run `make ungoogled-build` and `make ungoogled-smoke` for the optional privacy-focused image.
  91. - Run `make market-build` and `make market-smoke` for the optional market image.
  92. - On version upgrades, update every pinned DSH/image reference together, inspect upstream release notes, and rerun the full verification. Do not publish an unverified tag or a drifting `latest` tag.
  93. - Confirm both `linux/amd64` and `linux/arm64` when publishing multi-platform images.
  94. ## Diagnose failures
  95. Start with non-destructive evidence:
  96. ```bash
  97. docker compose config
  98. docker compose ps
  99. docker compose logs --tail=200 deepseek-harness
  100. docker compose ps -q deepseek-harness
  101. ```
  102. Pass the container ID reported by the last command to `docker inspect`; do not assume a fixed Compose project name.
  103. Check these common boundaries:
  104. - `3080` or `6080` already in use: choose different loopback host ports through `DSH_PORT` or `DSH_DESKTOP_PORT`.
  105. - Workspace not writable: verify the exact bind source and its ownership instead of making broad host directories writable.
  106. - Browser unhealthy: verify `/dev/shm`, the `6080` endpoint, and the `9222` Chromium debug endpoint from inside the container.
  107. - Profile or plugin failure: inspect the persisted profile and plugin logs before repairing; preserve backups created by the market repair tool.
  108. - Model request failure: verify provider URL, model name, and the presence of the expected environment variable without revealing its value.
  109. Do not use `docker compose down --volumes`, remove named volumes, or overwrite profile files without explicit user approval and a clear explanation of the data loss.
  110. ## Report completion
  111. State the selected image tag, workspace mount, exposed loopback URLs, container health, and verification performed. Distinguish a successful WebUI health check from a successful real model/tool call; perform the latter only when the user supplied a provider configuration and authorized the test.
README.md · README · 572 lines
  1. # DeepSeek Harness Docker
  2. [English](README.en.md) | 简体中文
  3. [![Upstream DSH](https://img.shields.io/github/v/release/deepseek-ai/deepseek-harness?include_prereleases&sort=semver&label=upstream%20DSH)](https://github.com/deepseek-ai/deepseek-harness/releases)
  4. [![Container Release](https://img.shields.io/github/v/release/runzhliu/deepseek-harness-docker?include_prereleases&sort=semver&label=container%20release)](https://github.com/runzhliu/deepseek-harness-docker/releases)
  5. [![Docker Image](https://img.shields.io/badge/docker.io-runzhliu%2Fdeepseek--harness-2496ED?logo=docker&logoColor=white)](https://hub.docker.com/r/runzhliu/deepseek-harness)
  6. [![GHCR](https://img.shields.io/badge/ghcr.io-runzhliu%2Fdeepseek--harness-2088FF?logo=github&logoColor=white)](https://github.com/users/runzhliu/packages/container/package/deepseek-harness)
  7. [![腾讯云 SkillHub](https://img.shields.io/badge/SkillHub-deepseek--harness--docker-00A4FF)](https://skillhub.cloud.tencent.com/skills/deepseek-harness-docker)
  8. [![Node.js](https://img.shields.io/badge/Node.js-24-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
  9. [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  10. DeepSeek Harness(DSH)以本地使用为中心,桌面版也延续了这一形态。企业内部推进 Agent 化,需要把运行环境部署到云上,按任务创建实例、动态分配资源,并支持快速迭代。**云上运行、动态供给、快速迭代,是企业内部 Agent 化的基础。**
  11. 本项目将官方 DSH npm 发行物封装为可复现的 Docker 运行环境,为通过 Kubernetes 部署和管理独立的 Agent 实例提供基础。默认提供 Web UI、非 root 的 Node.js 24 运行时与可视 Chromium/noVNC 桌面,可选插件市场和受保护局域网入口,不修改 DSH 源码。
  12. **DeepSeek Harness 最早一批非官方 Docker 镜像项目之一,自 [2026 年 8 月 13 日](https://github.com/runzhliu/deepseek-harness-docker/commit/0d12e3bdb6dc5c0f408870b73b1914359a4f9aca) 起持续维护。** 提供 Docker Hub / GHCR 双架构镜像、Docker Compose、Rootless Podman 和 Helm 部署,持续跟进官方版本。
  13. > 当前基线:`@deepseek-ai/dsh@0.2.2-rc.4`。DeepSeek Harness 仍处于预发布阶段;升级前应重新完成本文的构建和 Smoke Test。
  14. `0.2.2-rc.4` 直接对应官方 [`dsh-v0.2.2-rc.4`](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.2-rc.4) Release 与 npm Registry 的 [`@deepseek-ai/dsh@0.2.2-rc.4`](https://www.npmjs.com/package/@deepseek-ai/dsh/v/0.2.2-rc.4),并非本项目自定义版本。本项目封装 npm 成品而不从源码构建,因此以可安装的官方发行物为基线,并故意不发布漂移的 Docker `latest` 标签。
  15. `0.2.2-rc.2` 增强具名及多层 SubAgent、AgentTeam 和工作树审阅。归档会话默认会清理符合条件的 Git 工作树;自定义插件与 SDK 集成需要核对上游迁移说明。
  16. `0.2.2-rc.3` 新增实验性的 DeepSeek 历史会话导入插件,并修复 Windows 桌面版应用内更新问题。
  17. `0.2.2-rc.4` 改进了模型返回异常消息时的处理,并修复了桌面端无法创建 LiveShare 分享的问题。
  18. > **0.2.2 迁移:** 最低 Node.js 为 `24.9`;自定义插件需核对 Session 投影、工具执行和 PTC 接口。Web Fetch 允许内网地址,部署需自行限制出站网络;自定义模型应显式填写容量。升级前备份数据卷,降级使用旧卷备份。详见[官方说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.2-rc.2)。
  19. > **alpha.4 插件兼容性:** 第三方插件声明的 `engines.dsh` 优先用于判断 DSH 版本兼容性;未声明时继续沿用原有规则。升级第三方插件时应核对其支持范围。
  20. > **alpha.3 迁移提醒:** Web / Desktop 优先使用已保存凭据;Headless 默认只读取环境变量和 `.env`,不再读取已保存密钥。旧 Azure provider 名称 `azure-openai-responses` 需迁移为 `azure`。`--from-default-profile` 重建已有自定义 Profile 会替换其插件和设置,升级现有实例时请保留原 Profile。详见[官方更新说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-alpha.3)。
  21. > **升级提醒:** `0.1.7-alpha.1` 起 Session 日志为 V4。若从更早版本升级,必须先备份 `dsh-home`;依赖旧日志结构的工具需要适配 V4,降级前也应恢复升级前的卷备份,而不是让旧版直接读取已迁移数据。
  22. > **兼容性提醒:** 自定义 `spill-policy` 配置必须把 `maxInlineBytes` 改为按估算 Token 计数的 `maxInlineTokens`。内置 E2B 执行后端已移除,PTC 与 Workflow 服务已重命名;若从 `0.1.7-alpha.1` 以前升级,还需处理 Messages-only adapter、Profile-owned 设置、Bundle Agent Preset 和 Remote `readBytes` 迁移。详见[官方 Release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-alpha.1)。
  23. > **0.2.1 兼容性提醒:** 自动化任务重新成为 Web 内置能力,旧实验组合包选择会自动清理但已有任务保留。运行时 invariant 插件及各包的 `./invariant` 导出已移除;子路径插件不再读取独立 `package.json`;输入区原 `stats` 扩展拆为 `activity` 与 `usage`。依赖这些入口的自定义插件必须先适配。
  24. > **0.2.1-alpha.2 及更早版本:** 工具模式、Python PTC、Agent 指令与子代理接口需按[迁移说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-alpha.2)调整。本镜像保留回环端口与可选 Caddy LAN 入口。
  25. > 上游版本跟踪:每日运行的 [Upstream DSH version watch](.github/workflows/upstream-dsh.yml) 会同时检查 GitHub Release 与 npm。若新版 Release 已发布但 npm 制品尚不可用,工作流会创建或刷新等待 Issue 并保留当前可安装基线;同版本 npm 包可安装后,Issue 会自动切换为升级提醒,固定版本追平后再自动关闭。
  26. 📖 延伸阅读:[DeepSeek Harness GitHub 仓库深度解析](https://aik8s.run/ai-k8s/rag-agent/deepseek-harness-repository-analysis/) · [Docker、Compose 与 Helm 部署实战](https://aik8s.run/ai-k8s/rag-agent/deepseek-harness-runtime-containerization/)
  27. 🤖 **Agent Skill:**根目录的 [`SKILL.md`](SKILL.md) 已作为 [`deepseek-harness-docker`](https://skillhub.cloud.tencent.com/skills/deepseek-harness-docker) 发布到腾讯云 SkillHub,可供支持 Agent Skills 的客户端安装和使用。它指导 Agent 按本项目的安全边界完成 Docker Compose/Helm 部署、验证、升级与排障;这是部署辅助 Skill,不是 DSH 运行时插件。
  28. ![DeepSeek Harness 浅色 Web UI:新版首页与导航](assets/deepseek-harness-web.png)
  29. _浅色界面实拍(2026-11-18,DSH `0.2.2-rc.4`)。使用独立空白演示工作区,不包含个人会话或凭据,未配置模型,也未发起模型调用。_
  30. ## 项目状态
  31. | 能力 | 状态 | 验证结果 |
  32. | --- | --- | --- |
  33. | Dockerfile | 可用 | `linux/arm64`、`linux/amd64` 构建与原生 PTY 实际启动均已验证 |
  34. | Docker Compose | 可用 | Web token/cookie 认证、healthy、回环端口、重启持久化已验证 |
  35. | Rootless Podman | 可用 | `keep-id` 用户映射、bind mount 写入、命名卷持久化与回环端口已纳入 CI |
  36. | Helm | 可用 | 单副本 StatefulSet、PVC、Headless Service、NetworkPolicy;`helm lint --strict` 通过 |
  37. | Web UI | 本机默认;可选受保护 LAN | 默认仅回环访问;LAN overlay 提供 HTTPS、Basic Auth、DSH token/cookie 与同源 noVNC |
  38. | Headless | 可用 | 运行时注入 provider Secret;需在目标环境验证实际模型调用和沙箱 |
  39. | Chromium | 默认 + 可选隐私变体 | Debian Chromium 默认镜像;独立 ungoogled-chromium 双架构镜像会验证无 GCM `:5228` 活动 |
  40. ## DeepSeek Harness 深入分析
  41. 本节是配套技术文章的精简版。Cordis 架构、Agent 轮次和事件溯源持久化见 [GitHub 仓库深度解析](https://aik8s.run/ai-k8s/rag-agent/deepseek-harness-repository-analysis/);镜像设计、安全模型和容器验证矩阵见 [Docker、Compose 与 Helm 部署实战](https://aik8s.run/ai-k8s/rag-agent/deepseek-harness-runtime-containerization/)。
  42. ### 它是什么,不是什么
  43. [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 不是 DeepSeek 模型权重或推理引擎,而是一套 TypeScript AI Agent Runtime。它把模型适配、会话、工具、权限、工作区、插件、Web UI 与 Headless 入口装配在一起,最终发布为 [`@deepseek-ai/dsh`](https://www.npmjs.com/package/@deepseek-ai/dsh) CLI。更合适的专题归类是“AI Agent Runtime 的云原生化”,而不是“LLM 推理部署”。
  44. 截至 2026-08-13,上游仓库还没有 Dockerfile、Compose 或 Kubernetes 清单;同时 [`CONTRIBUTING.md`](https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.md) 明确表示暂不接受外部 Pull Request,并鼓励社区创建生态项目和教程。因此本项目采用独立社区实现,而不冒充官方镜像。
  45. ### 运行时分层
  46. ```mermaid
  47. flowchart TB
  48. CLI["dsh CLI"] --> PROFILE["Profile + Bundle + --patch layers"]
  49. PROFILE --> CORDIS["Cordis plugin graph"]
  50. CORDIS --> CORE["Agent / Session / Model / Tool / Sandbox"]
  51. CORDIS --> WEB["Web surface :3080"]
  52. CORDIS --> HEADLESS["Headless surface"]
  53. CORE --> WORKSPACE["/workspace"]
  54. CORE --> HOME["DSH_HOME: profiles / settings / credentials / sessions / storage"]
  55. ```
  56. 1. **CLI 与 Profile。** `dsh web` 是 Web profile 的快捷入口,`dsh --profile headless` 则走一次性或自动化场景。Profile 不是一份封闭配置,而是基础 bundle、界面 bundle、用户 patch 和命令行 `--patch` 按顺序叠加的结果。
  57. 2. **Cordis 组合层。** Harness 通过 Cordis Loader 把模型、会话、工具、Web Server、目录选择器等能力装成插件图;依赖注入决定激活顺序,配置 patch 通过稳定 `id` 覆盖目标行。本项目没有 fork 源码,而是复用这条官方扩展缝隙覆盖容器监听地址。
  58. 3. **Agent 核心。** 模型路由、系统提示词、会话持久化、工具调用、目标/计划、子 Agent 与工作区都在 Host 侧组合。Web 只是浏览器客户端,不是另一个 Agent 实现。
  59. 4. **Surface。** Web surface 提供浏览器交互,Headless surface 适合 CLI、CI 和批处理。二者共享核心插件与 `$DSH_HOME` 数据模型。
  60. ### 数据与持久化边界
  61. `DSH_HOME` 是容器化的关键边界。本项目显式设为 `/home/node/.dsh`,其中会出现:
  62. - `profiles/`:profile 的包清单、Cordis 配置和用户 patch;
  63. - `settings.yaml` 与凭据文件:模型设置及 Secret 引用/托管凭据;
  64. - `sessions/`:会话日志;
  65. - `storages/`:Workspace 等领域状态。
  66. 工作代码位于 `/workspace`,与内部状态卷分离。Compose 使用 `dsh-home` 命名卷加工作区 bind mount;Helm 使用 `dsh-home` PVC,并允许通过 `workspace.existingClaim` 挂载另一块工作区 PVC。这个分离让镜像可以重建,而会话与配置不会随容器消失。
  67. ### 为什么容器化并不只是 `npx`
  68. | 难点 | 上游行为 | 本项目决策 |
  69. | --- | --- | --- |
  70. | Node / glibc | 要求 Node 24.9+;部分用户二进制需要较新 glibc | 固定官方 `node:24-trixie` 非 slim,Debian 13 / glibc 2.41 |
  71. | 原生依赖与 Agent 工具 | `node-pty` 或第三方插件可能需要本机构建;Agent 需要常见开发命令 | 多阶段安装 DSH;runtime 有意保留 buildpack-deps 工具链,并补齐 `jq`、`less`、`ripgrep`、`rsync`、`zip` 等命令 |
  72. | Web 监听 | `0.2.1-alpha.2` 起配置层也拒绝通配地址 | DSH 监听回环;单个具体容器 IP 做 TCP 转发;宿主 3080/6080 只发布到 `127.0.0.1` |
  73. | Web 安全 | 有启动 token 认证与 Host/Origin 检查,可选原生 TLS;noVNC 无认证,工具可触发代码执行 | 容器默认 HTTP、回环发布;可选 Caddy HTTPS + Basic Auth;不提供公网 Ingress/LoadBalancer |
  74. | HMR | 启动后挂载配置 watcher,需要 Node internals | 仅给 DSH 主进程传 `--expose-internals`,不通过 `NODE_OPTIONS` 传播给 Agent 子进程 |
  75. | 目录选择器 | 浏览模式以 `os.homedir()` 为首页 | 将 `HOME` 指向可写 `/workspace`,避免只读 `/home/node` 的 EROFS |
  76. | 信号和子进程 | Agent 会创建 shell/PTY 子进程 | 使用 `tini` 转发信号和回收孤儿进程 |
  77. | 权限 | 工具需要工作区写入,但不应获得宿主权限 | UID 1000、只读根文件系统、drop ALL、no-new-privileges、最小挂载 |
  78. 默认基础镜像选择非 slim 是面向 coding agent 的明确取舍,而不是追求最小体积。Debian 13 Trixie 将 glibc 从 Bookworm 的 2.36 提升到 2.41,能运行更多按新系统构建的二进制;官方 Node 非 slim 变体基于 `buildpack-deps`,自带编译器、`make`、`git`、`curl`、`file`、`unzip`、`wget`、`xz` 等开发工具,本项目再显式安装 `jq`、`less`、`ripgrep`、`rsync` 和 `zip`。代价是基础镜像压缩体积比 slim 大约增加 330 MB;Smoke Test 会同时检查 Trixie、glibc 2.41 和完整命令清单,避免后续升级意外退化。
  79. 这里最需要强调的是 Web 监听:`0.2.1-alpha.2` 开始,Harness 的 CLI 和配置层都拒绝通配地址。本项目让 DSH 保持监听 `127.0.0.1:3080`,由入口脚本在**单个具体容器 IP** 上启动 TCP 中继,原样转发到回环地址,不修改 DSH 源码,也不改写 token、Cookie、Host/Origin 或 WebSocket 流量。这样既支持 Docker/Podman 端口映射,也保留 Kubernetes port-forward 和容器内健康检查。默认自动选择唯一的非回环 IPv4 地址(仅 IPv6 时选唯一的非链路本地地址);多网卡存在歧义时拒绝启动,需显式设置 `DSH_WEB_RELAY_INTERFACE`。不支持 host networking 或 `--port 0`。
  80. 默认 Compose 仍只发布宿主 `127.0.0.1`。需要受信任局域网访问时,显式叠加 `compose.lan.yaml`,由 Caddy 在指定 LAN 地址上终止 HTTPS、增加 Basic Auth,并把 noVNC 收进同一认证入口;DSH 仍执行自己的启动 token、签名 Cookie 与 Host/Origin 检查。直接改成 `-p 3080:3080`、NodePort、LoadBalancer 或公开 Ingress 仍会破坏这个安全模型。
  81. ### 容器与 Harness 沙箱的关系
  82. 容器不是 Harness 内部权限系统的替代品,两层保护的对象不同:
  83. - Docker/Kubernetes 限制进程能看到哪些宿主目录、Linux capabilities 和资源;
  84. - Harness 沙箱限制 Agent 工具在已进入容器的文件系统中能够执行什么。
  85. Linux Landlock、用户命名空间和原生 helper 的可用性会受宿主内核与容器运行时影响。本项目不会用 `--privileged`、Docker socket 或额外 capabilities 掩盖沙箱失败。发布前除“页面能打开”外,还必须在目标平台验证一次真实 bash/文件工具调用。
  86. #### 无 Landlock 内核的可选 bubblewrap 后端
  87. 若内核已经编译 Landlock、但没有放进当前 LSM 列表,应优先按发行版方式启用 Landlock 并重启;不要照搬其他发行版的 GRUB 命令,先核对 `/proc/cmdline`、内核配置和引导工具。若内核根本没有 Landlock(常见于部分 NAS/Appliance 内核),可在 **Docker Compose** 上显式使用 bubblewrap 变体:
  88. ```bash
  89. DSH_WORKSPACE=/absolute/path/to/project \
  90. docker compose -f compose.yaml -f compose.bwrap.yaml pull
  91. DSH_WORKSPACE=/absolute/path/to/project \
  92. docker compose -f compose.yaml -f compose.bwrap.yaml up -d --no-build
  93. ```
  94. 该 overlay 使用不可变镜像 `runzhliu/deepseek-harness:0.2.2-rc.4-r1-bwrap.1`,并增加 `seccomp=unconfined` 与 `systempaths=unconfined`,使非 root 的 `bwrap` 可以创建内部 user/mount/PID namespace 和挂载新的 `/proc`。它仍保留 UID 1000、只读根文件系统、`cap_drop: ALL`、`no-new-privileges` 和最小挂载;但两项设置确实扩大了外层容器可见的系统调用与 `/proc` 表面,因此不会成为默认配置。宿主还必须允许非特权用户命名空间。
  95. 此方案当前只承诺 Docker Compose,不应用于 rootless Podman 或 Kubernetes。Podman 主机若内核已有 Landlock,应优先在启动参数中启用对应 LSM。可以在目标 Docker 主机复现隔离边界测试:
  96. ```bash
  97. make bwrap-build
  98. make bwrap-smoke
  99. ```
  100. 测试会证明 bubblewrap 内 `/workspace` 可写,同时即使外层额外挂载一个可写目录,模型命令也无法写入该目录。相关背景和宿主案例见 [Issue #35](https://github.com/runzhliu/deepseek-harness-docker/issues/35)。
  101. ### 为什么 Kubernetes 使用 StatefulSet
  102. Harness 的 profile、模型设置、凭据、会话和 Workspace 索引都具有状态。单用户 Web 又不适合在没有会话协调的情况下横向扩容。因此 Helm Chart 固定一个 StatefulSet 副本:稳定地挂载 `dsh-home` PVC,升级时保留状态,卸载时保留 PVC,并明确拒绝把“加 replicas”伪装成高可用。未来只有在上游提供外部身份、多租户隔离和共享/并发安全的状态后端后,才适合讨论多副本服务化。
  103. ## 为什么不只是写 `FROM node` + `npx`
  104. 这个镜像处理了最容易漏掉的四个容器边界:
  105. - 固定 DSH 版本,并在构建时校验实际 CLI 版本;
  106. - 固定 pnpm 版本,使 `dsh plugin add` 能在运行时管理社区插件;
  107. - 使用非 root 用户和 `tini`,正确处理 Agent 启动的子进程与退出信号;
  108. - 把配置、凭据、会话和存储统一持久化到 `/home/node/.dsh`;
  109. - 把容器用户的交互主目录指向 `/workspace`,让 Web 目录选择器的新建操作落在可写工作区;
  110. - 通过容器专用 Cordis overlay 监听容器网络,同时只把宿主端口发布到 `127.0.0.1`。
  111. DeepSeek Harness Web 会用启动 token 换取签名浏览器 Cookie,并检查 Host/Origin;但本镜像默认使用 HTTP,Web API 可以执行代码,noVNC 端口也没有认证。因此默认方案是**本机单用户开发环境**。局域网访问必须使用下方显式启用的受保护入口;公网暴露不在支持范围内。
  112. ## 快速开始
  113. 在本目录执行:
  114. ```bash
  115. docker compose pull
  116. DSH_WORKSPACE=/absolute/path/to/your/project docker compose up -d --no-build
  117. docker compose ps
  118. docker compose logs --no-color deepseek-harness | grep 'dsh web:'
  119. ```
  120. 打开日志中 `dsh web:` 后面带 `?token=...` 的完整 <http://127.0.0.1:3080> 地址。Harness 会把当前进程的启动 token 换成签名 Cookie,再跳转到干净的根路径;直接打开不带 token 的根地址会返回 `401`。进入后在设置页配置模型和凭据。侧边栏的“浏览器桌面”按钮会在 Harness WebUI 内直接打开可交互的容器 Chromium;配置和浏览器 Profile 写入命名卷 `dsh-home`,重建容器后仍会保留。
  121. 未设置 `DSH_WORKSPACE` 时,Compose 使用独立的 `dsh-workspace` 命名卷,避免 Agent 意外修改本仓库。只有准备好明确的项目目录后,才通过 `DSH_WORKSPACE=/absolute/path/to/project` 改用 bind mount。
  122. 默认镜像修订版为 Docker Hub 上的 [`runzhliu/deepseek-harness:0.2.2-rc.4-r1`](https://hub.docker.com/r/runzhliu/deepseek-harness),同一份多架构制品也会发布到 GitHub Container Registry:[`ghcr.io/runzhliu/deepseek-harness:0.2.2-rc.4-r1`](https://github.com/users/runzhliu/packages/container/package/deepseek-harness)。`r1` 将同版本官方 Playwright MCP Browser Use attach 到可视 Chromium,并继续使用带版本的 noVNC 静态资源路径,避免升级后浏览器缓存混用不兼容的 ES Module。Compose 同时保留 `build` 配置,方便审查并从本目录复现镜像;如需本地构建,执行 `docker compose build --pull` 后再启动。
  123. ### Rootless Podman
  124. Podman `4.5` 和 `podman-compose 1.6.0` 或更新版本可使用专用 [`compose.podman.yaml`](compose.podman.yaml) overlay。较旧的 `podman-compose 1.0.x` 不能正确替换多文件 Compose 中相同目标路径的挂载;若发行版仓库版本过旧,可先执行 `pipx install 'podman-compose>=1.6.0'`。该 overlay 把当前 rootless 用户映射为镜像内的 `node` UID/GID 1000,并为工作区添加私有 SELinux 标签;这样无需用 root 运行 DSH,也无需递归修改宿主项目所有权:
  125. ```bash
  126. podman version
  127. podman-compose version
  128. podman info --format '{{.Host.Security.Rootless}}' # 应为 true
  129. DSH_WORKSPACE=/absolute/path/to/your/project \
  130. podman-compose -f compose.yaml -f compose.podman.yaml pull
  131. DSH_WORKSPACE=/absolute/path/to/your/project \
  132. podman-compose -f compose.yaml -f compose.podman.yaml up -d --no-build
  133. podman-compose -f compose.yaml -f compose.podman.yaml ps
  134. ```
  135. 这里明确使用 `podman-compose`,避免已安装 Docker Compose 时 `podman compose` 自动选中错误的外部 provider。Overlay 通过 `x-podman.in_pod: false` 关闭单服务部署不需要的 Pod 模式,因为 `keep-id` 用户命名空间不能与 `--pod` 同时使用。只挂载专用于该实例的项目目录;`:Z` 会在启用 SELinux 的主机上把该目录标记为本容器私有,不要对共享 home、仓库缓存或系统目录使用。停止服务使用 `make podman-down`,不会删除命名卷。维护者可运行 `make podman-smoke` 验证 rootless 身份、宿主文件所有权、重启持久化及回环端口。
  136. 若希望继续使用 Docker Compose 客户端,可启动 rootless Podman API socket,再让 Docker CLI 指向它;仍须叠加 `compose.podman.yaml`:
  137. ```bash
  138. systemctl --user enable --now podman.socket
  139. export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/podman/podman.sock"
  140. DSH_WORKSPACE=/absolute/path/to/your/project \
  141. docker compose -f compose.yaml -f compose.podman.yaml up -d --no-build
  142. ```
  143. 需要从 GHCR 拉取时,设置镜像仓库即可,其他 Compose 配置保持不变:
  144. ```bash
  145. DSH_IMAGE_REPOSITORY=ghcr.io/runzhliu/deepseek-harness docker compose pull
  146. DSH_IMAGE_REPOSITORY=ghcr.io/runzhliu/deepseek-harness \
  147. DSH_WORKSPACE=/absolute/path/to/your/project docker compose up -d --no-build
  148. ```
  149. ### 可选的 HTTPS 局域网访问
  150. 不要直接发布 `3080`/`6080`。可选 [`compose.lan.yaml`](compose.lan.yaml) 在指定 LAN IP 提供 Caddy HTTPS + Basic Auth,保留 DSH token/cookie 与 Host/Origin 校验,并同源代理 noVNC。
  151. 先创建私有配置并生成密码哈希:
  152. ```bash
  153. cp .env.lan.example .env.lan
  154. docker run --rm -it caddy:2.11.4-alpine caddy hash-password
  155. ```
  156. 编辑 `.env.lan`:填写**确切 LAN IP**(禁止 `0.0.0.0`)、客户端可解析的内网域名或 IP、单引号包裹的 bcrypt 哈希及可选工作区,然后启动:
  157. ```bash
  158. make lan-up
  159. make lan-logs
  160. ```
  161. Caddy 默认使用内部 CA。将根证书安装到受信任客户端的系统信任库:
  162. ```bash
  163. docker compose --env-file .env.lan -f compose.yaml -f compose.lan.yaml \
  164. cp lan-gateway:/data/caddy/pki/authorities/local/root.crt ./dsh-lan-root.crt
  165. ```
  166. 从 `dsh web:` 日志 URL 取 `?token=...`,首次用 `https://DSH_LAN_HOST:8443/?token=...` 打开。完成两层认证后即可使用干净地址。`make lan-down` 保留数据卷。8443 兼容 rootless 运行时。
  167. 该模式不是多租户:登录者共享会话、凭据及 Agent 权限;不互信用户须拆分实例和卷。用防火墙限制来源,禁止转发公网。`make lan-smoke` 可验证边界。
  168. ### 浏览器桌面、官方 Browser Use 与人工接管
  169. 镜像内置 Debian Chromium、中文字体、Xvfb/Openbox 桌面和 noVNC,并把官方 `@deepseek-ai/dsh-experimental-browser-use-playwright-mcp` 以 `mode: attach` 连接到 `http://127.0.0.1:9222`。模型自动化和用户看到的是同一个 Chromium:共享标签页、Cookie、登录态与持久化到 `/home/node/.dsh/chrome-profile` 的 Profile。
  170. | 层次 | 职责 |
  171. | --- | --- |
  172. | DSH 官方侧边栏 Browser | 用 iframe 快速展示可嵌入的 HTTP(S) 页面,不向模型提供工具;`0.1.7` 起 Web 默认关闭。 |
  173. | DSH 官方 Browser Use | 用 Playwright MCP 负责页面检查、点击、输入、截图和提取。 |
  174. | `@runzhliu/dsh-browser-desktop` | 负责真实浏览器生命周期、持久化 Profile、可视桌面和人工接管。 |
  175. 因此插件不再扩展第二套点击或抓取 API。模型应使用官方 Browser Use 工具完成网页操作;`browser_open` 只在用户要求“打开给我看”或需要人工接管时创建并激活标签页、自动展开桌面。对于拒绝 iframe 的 CSP/X-Frame-Options 页面、登录、验证码、下载、内网页面和交互调试,浏览器桌面仍是官方 iframe 侧边栏无法替代的运行层。官方 Browser Use 当前仍是实验性功能;一个 provider 实例同一时间只允许一个 live Session 独占 attach,其他会话仍可使用 `browser_open` 和人工桌面,待占用会话释放后新建或恢复会话即可取得自动化能力。Chromium 重启后,已断开的会话不会自动重连,也应新建或恢复会话。
  176. 默认使用 Playwright MCP。若要自行选择官方 Chrome DevTools MCP 或 Stagehand provider,启动前设置 `DSH_BROWSER_USE_ENABLED=0`,再通过 DSH Profile/插件管理配置一个 provider;同一 composition 不能同时注册两个 Browser Use provider。设置 `DSH_DESKTOP_ENABLED=0` 会同时停用内置 Browser Use attach 与浏览器桌面。
  177. 公开插件通过 Harness 的 `sidebar.footer.action` 与 `shell.overlay` 扩展点提供始终可见的“浏览器桌面”入口,点击后直接在 WebUI 内嵌可交互桌面,也可以选择新窗口打开 <http://127.0.0.1:6080/novnc-debian-1.6.0-2/vnc.html?autoconnect=1>。内嵌面板默认占页面约 68%,可拖动标题栏移动、拖动右下角缩放,并支持最大化/还原。浏览器意外退出或关闭后会自动重启。
  178. ![Harness WebUI 中可移动、缩放的内嵌 Chromium 浏览器](assets/browser-desktop-webui.png)
  179. _浅色界面实拍(2026-11-18,DSH `0.2.2-rc.4`、浏览器桌面插件 `0.1.6`):浏览器浮窗位于 Harness WebUI 内,图中打开的是官方 0.2.2-rc.4 GitHub Release 页面。_
  180. 该实现参考了 [`docker-antigravity`](https://github.com/runzhliu/docker-antigravity) 的可视桌面思路,但没有采用其 `amd64` 基础镜像和 Selkies,而是使用 Debian 原生架构软件包,因此 Apple Silicon 与 x86 Linux 均可运行。官方的 [Browser Use 架构](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/browser-use.md)和 [Sidebar Browser 限制](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-sidebar-browser/README.md)说明了两类浏览器能力的边界。6080 与 3080 一样只绑定宿主机回环地址;noVNC 原生端口没有认证,不能直接暴露。可选 LAN overlay 会把版本化 `/novnc-*` 路径放到与 WebUI 相同的 HTTPS 和认证入口下。
  181. ```bash
  182. docker compose exec deepseek-harness chromium-docker --version
  183. docker compose exec deepseek-harness \
  184. chromium-docker --headless=new --dump-dom https://example.com
  185. ```
  186. Compose 为 Chromium 配置了 1GB `/dev/shm`。启动器只对浏览器进程附加 `--no-sandbox`,以适配容器现有的 `cap_drop: ALL` 和 `no-new-privileges` 策略,不会放宽整个容器的权限。Agent 与脚本仍可通过 `chromium-docker --headless=new` 做无头渲染。
  187. #### 可选的 ungoogled-chromium 镜像
  188. 默认镜像继续使用 Debian Chromium,以保留 Debian 安全更新与发行版供应链。对浏览器空闲后台连接有严格要求时,可显式选择独立的 [`runzhliu/deepseek-harness:0.2.2-rc.4-r1-ungoogled.1`](https://hub.docker.com/r/runzhliu/deepseek-harness/tags) 变体:
  189. ```bash
  190. export DSH_IMAGE_VERSION=0.2.2-rc.4-r1-ungoogled.1
  191. docker compose pull
  192. DSH_WORKSPACE=/absolute/path/to/your/project docker compose up -d --no-build
  193. ```
  194. 该镜像固定 `ungoogled-chromium@152.0.7977.82-1`,分别校验 amd64 与 arm64 下载包的 SHA256。Smoke Test 会启动完整 Harness/noVNC 桌面、验证官方 Browser Use attach 配置并调用 `browser_open`,随后断言不存在 GCM `5228` 连接与 `google_apis/gcm` 日志。它还自动使用 `/home/node/.dsh/chrome-profile-ungoogled`,不会与默认 Debian Chromium 的 Profile 混用。GHCR 使用相同标签;Helm 可显式设置 `--set image.tag=0.2.2-rc.4-r1-ungoogled.1`。
  195. 这个变体采用 [`ungoogled-chromium-portablelinux`](https://github.com/ungoogled-software/ungoogled-chromium-portablelinux) 的社区 portable 构建,并非 Debian 官方软件包。[上游二进制索引](https://github.com/ungoogled-software/ungoogled-chromium-binaries)明确提示贡献者二进制不一定可复现、真实性无法完全保证;同时 Google Safe Browsing、同步、推送、Widevine 和扩展商店集成可能缺失或需要手动配置。因此它不会替换默认镜像,也不会发布为 `latest`。本地复现与验证:
  196. ```bash
  197. make ungoogled-build
  198. make ungoogled-smoke
  199. ```
  200. ### 独立安装浏览器插件
  201. 插件已经按 DSH bundle 规范拆到 [`plugins/dsh-browser-desktop`](plugins/dsh-browser-desktop/README.md),可独立打包:
  202. ```bash
  203. npm pack ./plugins/dsh-browser-desktop --pack-destination /tmp
  204. dsh plugin --profile web add /tmp/runzhliu-dsh-browser-desktop-0.1.6.tgz
  205. ```
  206. `0.1.6` 插件新增对 DSH `0.2.2` client module runtime 的兼容,同时保留 `0.1.2`、`0.2.0` 与 `0.2.1` 系列兼容;旧 DSH `0.1.0`/`0.1.1` RC 应继续使用插件 `0.1.1`。发布到 npm 后可直接执行 `dsh plugin --profile web add @runzhliu/dsh-browser-desktop`。该 npm 包只负责 Harness Host/WebUI 集成,不会自行安装 Chromium、Xvfb、noVNC 或官方 Browser Use provider;本仓库 Docker 镜像是完整的参考运行时。官方 DSH 通过 npm/GitHub 和 `dsh-plugin` GitHub topic 发现社区插件。
  207. ### 可选的 Super Agent 预装镜像
  208. 镜像 `runzhliu/deepseek-harness:0.2.2-rc.4-r1-superagent.1` 在插件市场版基础上预装 [DeepSeek Super Agent 原型](https://github.com/deepseek-ai/dsh-superagent-prototype) `0.1.0`,固定源码提交 [`6337fc8`](https://github.com/deepseek-ai/dsh-superagent-prototype/commit/6337fc823ce20251c8de8085948165c81aaa701e)。包含 GitHub CLI `2.103.3`、tmux 和 Git LFS;同名双架构镜像同时提供于 Docker Hub / GHCR。
  209. 上游将它定位为研究原型,并非正式 DeepSeek 产品。这个变体提供预安装环境:**首次启动暂停处理、关闭来源和自动评估,未连接仓库或模型**,需要你在 Superagent 面板完成配置。公开镜像使用上游代码及可审查的[容器兼容补丁](superagent/container-compat.patch),不包含本机的公司 GitLab 适配、内部模型、会话或凭据。
  210. 使用独立项目和数据卷;下面的端口可以与普通 3080 实例并存:
  211. ```bash
  212. DSH_PORT=3082 DSH_DESKTOP_PORT=6082 make superagent-pull
  213. DSH_PORT=3082 DSH_DESKTOP_PORT=6082 make superagent-up
  214. docker compose -p dsh-superagent -f compose.yaml -f compose.superagent.yaml logs --no-color deepseek-harness
  215. ```
  216. 从日志中取当前 `dsh web:` 的 token,在浏览器打开 `http://127.0.0.1:3082/?token=...`。进入侧栏 **Superagent**;首次显示“尚未配置仓库”等提示属于待配置状态。使用 `DSH_SUPERAGENT_WORKSPACE=/absolute/path/to/project` 指定专用于它的项目目录,或保留默认独立工作区卷。GHCR 用户可在上述 Make 命令前加 `DSH_IMAGE_REPOSITORY=ghcr.io/runzhliu/deepseek-harness`。
  217. 1. 在 DSH 设置中配置自己的模型;镜像不内置任何 API Key。
  218. 2. 在专用容器内登录 Agent 的 GitHub 账号:`docker compose -p dsh-superagent -f compose.yaml -f compose.superagent.yaml exec deepseek-harness gh auth login --web --git-protocol https`。CLI 配置保存在此实例的数据卷中。
  219. 3. 在 Superagent → 设置 → 来源中填写 GitHub 仓库与 `/usr/local/bin/gh`,配置允许发起工作的账号、规则和执行目录。先用仅观察模式核对行为,再按需要启用处理。飞书还需要额外安装、配置上游要求的 `lark-cli`。
  220. 该原型的 Executor 在容器内使用 `danger-full-access`;只挂载它需要的项目目录,不挂载 Docker Socket 或个人整个 home。它应单独运行,不与个人 DSH 混用。镜像会拒绝初始化已有普通 DSH 数据的卷;后续重启保留已保存的配置,不自动覆盖或重新暂停你的设置。`make superagent-down` 停止专用实例并保留数据。
  221. 容器适配增加当前 DSH 预发布版兼容声明、显式配置的宿主回环端口校验,并为原型管理 API 接入 DSH 的 cookie 登录校验;保留同源检查。仅支持回环入口,Super Agent 管理面不承诺现有 LAN overlay / Ingress 接入。构建验证源码 SHA-256,使用上游锁文件,并运行原型测试;运行时只保留插件发行文件与锁定的生产依赖。维护者执行 `make superagent-build` / `make superagent-smoke`,或运行 **Publish Super Agent images** 工作流,在 amd64 / arm64 原生测试后发布不可变标签。
  222. ![Superagent 预装镜像的浅色初始界面](assets/deepseek-harness-superagent.png)
  223. _使用独立空白实例拍摄;未登录 GitHub、未配置模型、未发送工单或模型请求。_
  224. 实验性的 [Alertmanager 来源插件](plugins/dsh-alertmanager/README.md) 可接收告警和恢复事件,在 Superagent 中展示事故与唯秘群组执行计划。默认仅观察;需另行安装,并接入经过验证的 IM 网关后才能真实建群,当前公开镜像未预装此插件。
  225. ### 可选的社区插件市场
  226. 默认镜像、默认 Compose 和 Helm Chart **不包含也不加载插件市场**,它们只跟随官方 `@deepseek-ai/dsh` 发行物。需要图形化浏览和安装社区插件时,可以显式选择独立的 [`dshmarket`](https://github.com/dsh-market/dsh-market) 变体:
  227. ```bash
  228. docker compose -f compose.yaml -f compose.market.yaml pull
  229. DSH_WORKSPACE=/absolute/path/to/your/project \
  230. docker compose -f compose.yaml -f compose.market.yaml up -d --no-build
  231. ```
  232. 该变体使用明确区分的 `runzhliu/deepseek-harness:0.2.2-rc.4-r1-market.1` 标签,固定 `dshmarket@1.66.9`,不会替换默认 DSH 标签或 `latest`。它属于社区可选集成,不是 DeepSeek 官方组件,也不代表本项目对市场条目的审核或背书。
  233. ![可选 market 镜像中的浅色社区插件市场](assets/plugin-market-webui.png)
  234. _可选 market 镜像实拍(2026-11-18,DSH `0.2.2-rc.4`、`dshmarket@1.66.9`);默认镜像没有此页面。目录与兼容性标记会变化,截图仅浏览,未安装图中插件。_
  235. 市场自身在构建期固定并打入可选镜像;通过市场安装的插件和 pnpm store 会写入持久化的 `dsh-home` 卷。安装过程需要容器能够访问 npm/GitHub,第三方包的构建脚本仍应在审查后单独授权。市场内的一键重启已禁用,变更需要通过 `docker compose restart` 或 Kubernetes rollout 进入新进程。
  236. 本地验证可选变体:
  237. ```bash
  238. make market-build
  239. make market-smoke
  240. ```
  241. Helm 仍默认官方 DSH 镜像;只有明确设置 `--set image.tag=0.2.2-rc.4-r1-market.1` 时才使用市场变体。
  242. 如果复用的 `dsh-home` 曾被另一个 pnpm 主版本处理,安装时可能看到 `ERR_PNPM_UNEXPECTED_STORE`。先停止 DSH,再显式执行一次迁移:
  243. ```bash
  244. docker compose -f compose.yaml -f compose.market.yaml stop deepseek-harness
  245. docker compose -f compose.yaml -f compose.market.yaml run --rm --no-deps \
  246. --entrypoint dsh-market-repair-store deepseek-harness
  247. docker compose -f compose.yaml -f compose.market.yaml up -d --no-build
  248. ```
  249. 迁移只按现有 `package.json` 重新链接依赖,固定使用 `/home/node/.dsh/pnpm-store`,并传入 `--ignore-scripts`。旧的 `node_modules` 会保留在 `/home/node/.dsh/backups/pnpm-store-*`,确认插件正常后再自行清理。
  250. 可选镜像启动时还会检查已有的 `profiles/web/cordis.patch.yml`:如果它是普通文件但因旧 UID 不可写,入口脚本会用内容完全相同、归当前运行用户所有的副本替换它,从而恢复插件开关;不会递归修改整个卷,符号链接或非普通文件只会给出警告。
  251. 本公开分支不打包任何公司内部模型、凭据、Skill 或个人工作区挂载。模型在 Harness 设置页配置;额外凭据和私有扩展应放在运行时 Secret、被忽略的 `.env` 或本机 `compose.local.yaml` 中。
  252. 查看日志和停止服务:
  253. ```bash
  254. docker compose logs -f deepseek-harness
  255. docker compose down
  256. ```
  257. `docker compose down` 不删除命名卷。只有明确执行 `docker compose down --volumes` 才会删除持久化的配置、凭据、会话,以及默认 `dsh-workspace` 卷中的全部工作区数据;使用该参数前必须先备份需要保留的内容。
  258. ## 直接使用 Docker
  259. 构建镜像:
  260. ```bash
  261. docker build -t runzhliu/deepseek-harness:0.2.2-rc.4-r1 .
  262. ```
  263. 启动 Web UI:
  264. ```bash
  265. docker volume create dsh-home
  266. docker run --rm \
  267. --name deepseek-harness \
  268. --publish 127.0.0.1:3080:3080 \
  269. --publish 127.0.0.1:6080:6080 \
  270. --shm-size 1g \
  271. --mount type=volume,src=dsh-home,dst=/home/node/.dsh \
  272. --mount type=bind,src="$PWD",dst=/workspace \
  273. runzhliu/deepseek-harness:0.2.2-rc.4-r1
  274. ```
  275. 启动命令会直接打印带 token 的访问地址,请打开该完整地址。不要把端口参数改成 `-p 3080:3080`,也不要把它部署到公开 Ingress;这里的 Web 默认未配置 TLS,6080 上的 noVNC 也没有认证。
  276. ## Headless 模式
  277. 镜像的入口等价于执行 `dsh`,因此可以用运行参数覆盖默认 Web 命令:
  278. ```bash
  279. docker run --rm \
  280. --env DEEPSEEK_API_KEY \
  281. --mount type=volume,src=dsh-home,dst=/home/node/.dsh \
  282. --mount type=bind,src="$PWD",dst=/workspace \
  283. runzhliu/deepseek-harness:0.2.2-rc.4-r1 \
  284. --profile headless "summarize this repository"
  285. ```
  286. Headless 从 `0.2.1-alpha.3` 起默认只读取环境变量和 `.env` 中的密钥,不读取 Web 设置里保存的密钥。按所选模型提供运行时环境变量或 Secret;不要把 API Key 写进 Dockerfile、镜像层或构建参数。
  287. ## Kubernetes / Helm
  288. `charts/deepseek-harness` 使用单副本 StatefulSet。`/home/node/.dsh` 由 PVC 持久化,工作区可以使用独立的现有 PVC;Chart 不创建 Ingress 或 LoadBalancer,并默认创建拒绝 Pod 入站流量的 NetworkPolicy。
  289. 默认使用已发布的 Docker Hub 镜像,直接安装 Chart:
  290. ```bash
  291. helm upgrade --install deepseek-harness charts/deepseek-harness \
  292. --namespace deepseek-harness \
  293. --create-namespace \
  294. --set image.repository=runzhliu/deepseek-harness \
  295. --set image.tag=0.2.2-rc.4-r1
  296. ```
  297. 本机开发集群也可以直接拉取默认的 `runzhliu/deepseek-harness`,或先用 `kind load docker-image` / `minikube image load` 导入同名本地镜像。
  298. 通过 API Server 安全转发到本机浏览器:
  299. ```bash
  300. kubectl -n deepseek-harness rollout status statefulset/deepseek-harness
  301. kubectl -n deepseek-harness port-forward service/deepseek-harness 3080:3080 6080:6080
  302. ```
  303. 另开终端执行 `kubectl -n deepseek-harness logs statefulset/deepseek-harness | grep 'dsh web:'`,然后打开日志中带 token 的完整 <http://127.0.0.1:3080> 地址;内嵌桌面通过同一条命令转发到 <http://127.0.0.1:6080>。不要把无 TLS 的 Web surface 或无认证的 noVNC 改成 NodePort、LoadBalancer 或直接接入 Ingress。
  304. 如需通过 Secret 注入 provider 环境变量:
  305. ```bash
  306. kubectl -n deepseek-harness create secret generic dsh-provider-credentials \
  307. --from-literal=DEEPSEEK_API_KEY='replace-me'
  308. helm upgrade deepseek-harness charts/deepseek-harness \
  309. --namespace deepseek-harness \
  310. --reuse-values \
  311. --set credentials.existingSecret=dsh-provider-credentials
  312. ```
  313. 如需持久化工作区,先创建 PVC,再设置 `workspace.existingClaim`。未设置时 `/workspace` 是临时 `emptyDir`。卸载 Chart 后,StatefulSet 创建的 `dsh-home` PVC 默认保留;确认不再需要配置、凭据和会话后再手动删除。
  314. ```bash
  315. helm uninstall deepseek-harness --namespace deepseek-harness
  316. kubectl -n deepseek-harness get pvc
  317. ```
  318. ## 升级版本
  319. 从 `0.2.2-alpha.2` 升级到 `0.2.2-rc.4` 时,需要 Node.js **24.9 或以上版本**。此前手动启用独立 Git 工作树插件的用户,应先备份配置,再从 profile 的 `package.json` → `dsh.profile.bundles` 移除 `@deepseek-ai/dsh-experimental-tool-worktree`;该入口已合并到上游「变更请求与工作树」。模型与凭据配置无需因此重置。
  320. 构建参数控制安装的 DSH 版本:
  321. ```bash
  322. docker build \
  323. --build-arg DSH_VERSION=0.2.2-rc.4 \
  324. --build-arg IMAGE_VERSION=0.2.2-rc.4-r1 \
  325. -t runzhliu/deepseek-harness:0.2.2-rc.4-r1 .
  326. ```
  327. Compose 分别使用上游版本和不可变镜像修订版:
  328. ```bash
  329. DSH_VERSION=0.2.2-rc.4 DSH_IMAGE_VERSION=0.2.2-rc.4-r1 docker compose build --pull
  330. ```
  331. 维护者可用 `make push` 构建并推送同一个不可变修订标签下的 `linux/amd64` 与 `linux/arm64` manifest。目标标签已经存在时命令会拒绝覆盖,也不会创建 `latest` 标签。
  332. 可选市场变体使用独立的 `make market-push`,只发布带 `-market.1` 后缀的双架构标签,不改变默认镜像。
  333. [Mirror Docker Hub images to GHCR](.github/workflows/publish-ghcr.yml) 工作流使用现有 Docker Hub manifest 创建 GHCR 碳拷贝,不重新构建镜像。发布以 `image-v` 开头的 GitHub Release 时会同步基础标签;维护者也可手动指定版本,并选择同时同步 `-market.1` 变体。同步后会比较源和目标的全部平台 manifest digest,且不会创建 `latest`。
  334. 不要默认安装 `latest`。RC 版本正在快速变化,固定版本才能让问题可复现。
  335. ## 安全边界
  336. - 容器默认以镜像内的 `node` 用户(UID/GID 1000)运行;如果宿主工作区拒绝该 UID 写入,需要调整目录权限或构建适配本机 UID 的派生镜像。
  337. - Web 目录选择器中的“主目录”是 `/workspace`,不是保存内部配置的 `/home/node`;通过 Compose 或 Kubernetes 挂载的工作区必须可由 UID 1000 写入。
  338. - DSH 服务丢弃全部 Linux capabilities;LAN gateway 因官方 Caddy 二进制的 file capability 仅保留 `NET_BIND_SERVICE`。两者均启用 `no-new-privileges`、只读根文件系统和独立 `/tmp` tmpfs。
  339. - 只挂载需要 Agent 操作的工作区。不要挂载宿主根目录、`~/.ssh`、云凭据目录或 Docker socket。
  340. - Docker 隔离不是多租户安全沙箱。不要把这个实例交给不受信任用户,也不要把未审查的插件装进持久化配置卷。
  341. - LAN overlay 只为可信内网增加传输加密和外层认证,不提供用户级授权或会话隔离;始终绑定确切 LAN IP、限制防火墙来源,并为不互信用户部署独立实例。
  342. - DeepSeek Harness 自己的 Linux 沙箱能力受宿主内核和容器运行时影响;镜像不会通过 `--privileged` 或额外 capabilities 绕过失败。应保留其默认权限模式,并验证真实工具调用。
  343. ## Smoke Test
  344. 每次升级至少完成以下检查:
  345. ```bash
  346. docker run --rm --entrypoint dsh runzhliu/deepseek-harness:0.2.2-rc.4-r1 --version
  347. docker run --rm --entrypoint dsh runzhliu/deepseek-harness:0.2.2-rc.4-r1 \
  348. web --patch /opt/deepseek-harness/web.cordis.patch.yml --dump-config
  349. docker compose up -d
  350. test "$(curl --silent --output /dev/null --write-out '%{http_code}' http://127.0.0.1:3080/)" = 401
  351. make smoke
  352. make lan-smoke
  353. docker compose ps
  354. docker compose logs --no-color deepseek-harness
  355. ```
  356. 通过标准包括:CLI 版本等于构建版本;dump 后的 `webserver.config.host` 为 `127.0.0.1`,另有单个具体容器 IP 上的 TCP 中继;未认证首页返回 `401`,启动 token 能换取 Cookie 并加载首页;容器进入 healthy;日志没有配置或插件加载错误;容器不会尝试调用宿主默认浏览器。真正发布镜像前还要分别在 `linux/amd64` 和 `linux/arm64` 上构建并实际 spawn PTY,因为终端与沙箱相关依赖包含原生模块。仓库提供 `make verify`、`make build` 和 `make smoke` 作为默认入口;可选市场另用 `make market-build` 和 `make market-smoke`,并额外验证默认镜像中不存在市场包。
  357. ## 常见问题
  358. 如果 Web 新建文件夹时报 `EROFS: read-only file system, mkdir '/home/node/...'`,说明容器仍在运行早期镜像或旧容器。当前镜像把目录选择器的主目录设为 `/workspace`。重新构建并强制重建容器:
  359. ```bash
  360. docker compose build
  361. docker compose up -d --force-recreate
  362. docker compose exec deepseek-harness node -e "console.log(require('node:os').homedir())"
  363. ```
  364. 最后一条命令应输出 `/workspace`。如果错误变成 `/workspace` 下的 `EACCES`,则是宿主 bind mount 与容器 UID 1000 的权限不匹配;修正工作区所有权/权限,或构建使用匹配 UID 的派生镜像,不要改成 root 运行。
  365. ## 文件
  366. | 文件 | 用途 |
  367. | --- | --- |
  368. | `Dockerfile` | 固定版本的非 root DSH 运行时,默认启动 Web UI |
  369. | `Dockerfile.market` | 从默认镜像派生、固定第三方市场版本的可选镜像 |
  370. | `Dockerfile.bwrap` | 为缺少 Landlock 的 Docker 主机提供 bubblewrap 的可选派生镜像 |
  371. | `web.cordis.patch.yml` | 回环 Web 监听与官方 Browser Use / 浏览器桌面集成 |
  372. | `scripts/dsh-web-relay.cjs` | 单个具体容器 IP 到 DSH 回环监听的原始 TCP 中继 |
  373. | `compose.yaml` | 持久化、回环端口和收紧后的运行时配置 |
  374. | `compose.market.yaml` | 显式选择第三方社区市场镜像的可选 Compose overlay |
  375. | `compose.bwrap.yaml` | 显式选择 bubblewrap 沙箱镜像并开放其所需命名空间操作的可选 overlay |
  376. | `compose.podman.yaml` | rootless Podman 的 `keep-id` 与 SELinux workspace overlay |
  377. | `compose.lan.yaml` | HTTPS、Basic Auth、trusted-host 和同源 noVNC 的可选 LAN overlay |
  378. | `config/Caddyfile.lan` | 受保护局域网入口的 Caddy 配置 |
  379. | `.env.lan.example` | 不含 Secret 的 LAN 配置模板 |
  380. | `web.market.cordis.patch.yml` | 只由可选市场派生镜像使用的 profile 配置 |
  381. | `plugins/dsh-browser-desktop/` | 可独立发布的 DSH 浏览器桌面 bundle |
  382. | `charts/deepseek-harness/` | 单副本 StatefulSet、PVC、Service 和 NetworkPolicy |
  383. | `scripts/smoke.sh` | CLI、配置、原生 PTY 和 HTTP 启动验证 |
  384. | `scripts/bwrap-smoke.sh` | bubblewrap 工作区写入与越界拒绝验证 |
  385. | `scripts/lan-smoke.sh` | LAN gateway 的 TLS、认证、Origin、noVNC 与端口边界验证 |
  386. | `scripts/podman-smoke.sh` | rootless 用户映射、持久化、Web/noVNC 和端口边界验证 |
  387. | `.github/workflows/ci.yml` | Compose/Helm 校验和双架构镜像 Smoke Test |
  388. | `.dockerignore` | 把构建上下文限制到镜像真正需要的文件 |
  389. 本目录是社区实现,不代表 DeepSeek 官方发布的容器镜像。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.