多用户门户 imzry/dsh-team

DSH-Portal · DeepSeek Harness 企业级多人平台

本项目依据《DeepSeek-Harness 企业级多人平台-产品设计文档.md》（v1.1）实现。这是一个服务器集中部署、浏览器访问、多用户数据隔离的企业级平台：以门户统一认证，为每个用户拉起独立的 DeepSeek Harness（DSH）实例，并通过网关做统一反代、推理并发控制、密级与内容审计合规。

设计文档（Single Source of Truth）位于仓库根目录：DeepSeek-Harness企业级多人平台-产品设计文档.md。所有实现决策遵循文档；未覆盖细节在代码中以 // DECISION: 标注。

目录

1. 架构与模块
2. 目录结构
3. 本地开发
4. 生产部署（完整流程）
5. 已实现功能
6. 关键实现决策
7. 附录：环境变量参考
8. 附录：端口与目录清单
9. 常见问题 / 注意

1. 架构与模块

员工 Win7 浏览器 (Chromium >= 86) │ http://dsh.corp.local (内网 DNS) ▼ Nginx（静态资源 + 反代 /api /app /infer） │ ┌─────▼─────────────────────────────────────────────────┐ │ 单进程 Node 应用 (Fastify) │ │ ├─ Portal API (/api) 认证/团队/附件/审计/管理后台 │ │ ├─ Gateway (/app/u/:id) DSH 反代 + WS + polyfill │ │ ├─ 推理代理 (/infer/:id/v1) 信号量+敏感词+记账 │ │ └─ Instance Manager │ │ └─ dsh-adapter（唯一 DSH 行为适配层） │ └─────┬──────────────────────────┬──────────────────────┘ ▼ ▼ KES v8 / DM8 (PostgreSQL) /srv/dsh-platform
instances/{uid} teams/{tid} attachments/…
▼
DSH 实例池 inst-1001 (127.0.0.1:20101) … ≤ 100 ▼ 8×Ascend 910B 推理服务 (OpenAI 兼容)

关键约定（源自文档）：

- 实例池架构：每用户一个独立 DSH 进程 + 独立数据目录，进程/目录/网络三级隔离。不改 DSH 源码。
- dsh-adapter：所有依赖 DSH 行为的代码（启动命令、健康检查、模板、挂载组装、反代路径规则）集中于此，DSH 升级只改这一处（NFR-11）。
- 推理走网关代理：/infer/{uid}/v1/...，才能做全站并发控制与输出侧敏感词过滤（doc 4.4）。
- 完全离线部署：运行时不联网，所有依赖随离线包携带（NFR-10）。

2. 目录结构

dsh-team/
├── README.md
├── package.json # npm workspaces：packages/* 与 web ├── config/ │ ├── portal.env.example # 运行时环境变量模板 │ ├── nginx/dsh-portal.conf # Nginx 反代配置 │ └── systemd/dsh-portal.service # systemd 单元 ├── db/init.sql # 建表 DDL（KES/DM8 兼容） ├── packages/server/ │ ├── package.json │ └── src/ │ ├── index.js # 启动入口（含 dev 自动迁移） │ ├── app.js # Fastify 组装 │ ├── config.js # 运行配置（环境变量） │ ├── cli.js # migrate/seed 命令行 │ ├── db/ # Knex 纯 PostgreSQL 方言迁移 + 连接 │ ├── shared/ # 常量、加密(scrypt/csrf/token)、密级、响应封装 │ ├── services/ # auth/session/audit/team/attachment/usage/skill/sensitive-word/config │ ├── instance-manager/ # 实例生命周期状态机/端口分配/队列/idle 回收 │ ├── dsh-adapter/ # DSH 行为适配层（唯一） │ ├── gateway/ # app 反代 + 推理代理(信号量/敏感词/记账) │ ├── plugins/ # auth（fastify-plugin）、错误处理 │ ├── routes/ # 门户 + 管理后台路由 │ └── test/ # 集成冒烟测试（node:test + pg-mem） ├── web/ # Vue 3 + Vite + Element Plus 前端（es2019） ├── scripts/ # install/update/backup/restore/monitor/offline-pack/smoke-test ├── template/ # 实例模板（全局 AGENTS.md + 技能库） ├── runtime/ # （打包机）放 Node v22 离线包，见 4.1 ├── dsh-runtime/ # （打包机）放 DSH 本体离线包（bin/dsh），见 4.1 ├── plugins/ # （打包机）放 DSH 插件 tgz，见 4.1 └── data/ # 运行数据（gitignore）

3. 本地开发

开发环境使用 pg-mem（内存 PostgreSQL 模拟器）与 DSH_MODE=fake（DSH 桩进程），无需真实 KES/DSH 即可跑通全流程。

3.1 安装依赖

npm install # 一次性安装 server + web 依赖

3.2 启动后端（单进程，自动迁移+种子）

非生产环境默认自动使用开发模式：内存数据库（pg-mem）、DSH 桩进程（DSH_MODE=fake）、进程内自动迁移+种子。因此无需配置任何环境变量：

根目录
npm run dev -w @dsh-portal/server

或在 packages/server 下
npm run dev

如果需要连接本地真实数据库，显式覆盖即可：

$env:DB_CLIENT='pg' # 连接本地/内网 PostgreSQL（KES/DM8 兼容） $env:DB_PASSWORD='xxx'
npm run dev

默认监听 http://127.0.0.1:8080。种子管理员：工号 admin，初始密码 Admin@12345（首次登录强制改密）。

3.3 启动前端

npm run web:dev

浏览器访问 http://localhost:5173（Vite 已代理 /api、/app、/infer 到 8080）。

3.4 运行测试

$env:DB_CLIENT='pg-mem'; $env:DSH_MODE='fake'
node --test test/smoke.test.js # 在 packages/server 下

测试覆盖：认证、CSRF、密级、团队、实例拉起、敏感词 block、推理记账+审计、用户导入、附件密级校验。

4. 生产部署（完整流程）

部署架构：单台 Linux 应用服务器承载门户+网关+实例池+前端；独立 910B 推理服务器承载模型；数据库与平台同机或独立（KES v8 / DM8，PostgreSQL 协议）。整条链路物理隔离、零公网访问。

4.0 部署前准备清单

应用服务器：

| 项 | 要求 |
| 操作系统 | RHEL/CentOS 8+、Kylin、openEuler 等 x86_64 Linux |
| 硬件 | 建议 ≥ 32C / 128G 内存 / 2T 磁盘（见文档第 12 章容量规划） |
| Node 运行环境 | 无需预装，离线包自带 Node v22 |
| Nginx | 需已安装（或使用发行版离线源安装） |
| 数据库 | 人大金仓 KES v8（推荐）/ 达梦 DM8，服务已就绪并有 dshportal 库 |
| 系统用户 | 脚本自动创建 dshrunner；亦可手动预建 |
| 出站网络 | 必须为零（iptables 默认禁出站更佳） |

网络 / 端口：

| 端口 | 监听 | 用途 |
| 80 / 443 | 0.0.0.0 | Nginx（对内网开放） |
| 8080 | 127.0.0.1 | Portal/Gateway（仅回环） |
| 20001–20999 | 127.0.0.1 | DSH 实例池（仅回环） |
| 54321 | 127.0.0.1 | 数据库（默认；按实际调整） |

浏览器：全员需 Chromium ≥ 86（360 极速模式 / Chrome 109 离线包）。上线前按文档附录 A 摸底。

4.1 在联网机准备离线物料

在打包机（可联网）把以下外部产物放入仓库里对应的暂存目录（这些是外部二进制/包，不在代码仓库内，目录名见下方说明）。目录已存在并附有 README：

| 目录 | 放入内容 | 说明 |
| runtime/ | node-v22-linux-x64.tar.xz | Node v22 官方离线包（安装脚本解到 runtime/node） |
| dsh-runtime/ | DSH 官方离线包（如 dsh-v1.2.3.tgz），解包后需有 bin/dsh | DSH 本体；平台适配层调用 $DSH_RUNTIME_ROOT/bin/dsh |
| plugins/ | dsh-gov、randomUUID polyfill 等 .tgz | 打进实例模板 template/plugins，新实例继承 |

dsh-runtime/ 与 plugins/ 不是平台代码的一部分：平台不修改也不内置 DSH（NFR-11），DSH 本体必须由你从 DSH 官方渠道获取后放到 dsh-runtime/。

放入示例：

cp node-v22-linux-x64.tar.xz runtime/
cp dsh-v1.2.3.tgz dsh-runtime/ && tar -xzf dsh-runtime/dsh-v1.2.3.tgz -C dsh-runtime && ls dsh-runtime/bin/dsh
cp dsh-gov-.tgz plugins/

dsh-adapter 读取 $DSH_RUNTIME_ROOT/bin/dsh 作为 DSH 可执行文件；生产环境需 DSH_MODE=real。

4.2 制作离线包（联网机）

cd <repo>bash
chmod +x scripts/.sh
./scripts/offline-pack.sh 1.0.0

产物：dist/dsh-portal-offline-v1.0.0.tar.gz

打包内容：app/server（含 node_modules）、web/dist、config、db、scripts、template、runtime/node、plugins/、manifest.sha256。全程不执行任何 npm install。

离线包体积预估 ≤ 2G。制作完成后，务必先在联网机的断网容器/虚拟机里完整演练一次全新安装，通过后再拷入内网（文档 11.1 第 4 条）。

4.3 拷入内网并校验完整性

用 U 盘 / 内网 FTP 将离线包拷入应用服务器，校验清单： bash
cd /opt
tar -xzf dsh-portal-offline-v1.0.0.tar.gz
cd dsh-portal-offline-v1.0.0
sha256sum -c manifest.sha256

4.4 一键安装

以 root 执行（脚本会用 systemd 托管服务）： bash
cd /opt/dsh-portal-offline-v1.0.0
BUNDLE=$(pwd) ./scripts/install.sh

install.sh 逐步完成：

1. 建用户/目录：dshrunner + /srv/dsh-platform/{app,runtime,template,data/{instances,teams,attachments,backups,logs}}。
2. 安装 Node 运行时：解包 node-v22-linux-x64.tar.xz 至 runtime/node，链接 /usr/local/bin/{node,npm}。
3. 拷贝程序与前端：app/server（含 vendored node_modules）、app/web（dist）、template/。
4. 生成 .env：若缺失，从 config/portal.env.example 复制到 /srv/dsh-platform/.env。
5. 安装 Nginx 与 systemd：dsh-portal.conf、dsh-portal.service。
6. 初始化数据库：用 psql 执行 db/init.sql（需 .env 中的 DB_；若数据库已由 DBA 预建，可跳过并用 cli.js migrate + cli.js seed）。
7. 生成实例令牌密钥：若 INSTANCE_TOKEN_SECRET 为空，用 /dev/urandom 随机生成并回写 .env。
8. 修复属主/权限：chown -R dshrunner:dshrunner，chmod 700 data。
9. 启动并冒烟自检：systemctl enable --now dsh-portal，运行 smoke-test.js 验证 healthz + 管理员登录。

4.5 配置真实密钥与数据库连接（关键）

安装完成后，编辑 /srv/dsh-platform/.env，务必修改以下项： ini
DB_PASSWORD=CHANGE_ME # 数据库账号密码
INFER_API_KEY=CHANGE_ME_REAL_KEY # 真实 910B 推理服务 Key（平台统一持有，用户不可见）
INFER_BASE_URL=http://<910B-IP>:<PORT> # 910B OpenAI 兼容端点 /v1
INSTANCE_TOKEN_SECRET=CHANGE_ME # 实例令牌签名密钥（随机已生成，可改写）
ADMIN_INITIAL_PASSWORD=Admin@12345 # 首次引导管理员初始密码（登录后再改）

然后 chmod 600 .env（属主 root），并重启： bash
set -a; . /srv/dsh-platform/.env; set +a
systemctl restart dsh-portal

首次启动会由 seed 幂等写入默认安全级别、系统配置与 admin 引导账号。

4.6 数据库分离初始化（若由 DBA 预建）

若数据库非脚本初始化，可先停止服务、再执行： bash
set -a; . /srv/dsh-platform/.env; set +a
cd /srv/dsh-platform/app/server
/srv/dsh-platform/runtime/node/bin/node src/cli.js migrate
/srv/dsh-platform/runtime/node/bin/node src/cli.js seed
systemctl start dsh-portal

4.7 放置 DSH 本体与插件

把离线包中的 DSH 运行时解到 $DSH_RUNTIME_ROOT，确保存在： bash
mkdir -p /srv/dsh-platform/dsh-runtime
tar -xzf /opt/dsh-runtime/dsh-v<ver>.tgz -C /srv/dsh-platform/dsh-runtime
ls -l /srv/dsh-platform/dsh-runtime/bin/dsh # 必须存在

插件（如 dsh-gov、randomUUID polyfill）随 template 安装到每个实例： bash
cp /opt/plugins/.tgz /srv/dsh-platform/template/plugins/ 2>/dev/null || true

涉及 DSH 内部行为的集成点（启动命令、反代 Host/Origin、包兼容性）需先在 Staging 用真实 DSH 跑附录 B 验证清单再固化（见 5 章说明）。

4.8 验证部署（验收清单） bash

1) 服务存活

curl http://127.0.0.1:8080/api/healthz
systemctl status dsh-portal --no-pager

2) 冒烟（含健康检查 + 管理员登录）

/srv/dsh-platform/app/scripts/smoke-test.js

3) 内网入口

curl http://<server-ip>/api/healthz
在任一 Chromium ≥ 86 浏览器中确认：

- 登录 http://<server-ip>/（工号 admin / Admin@12345，首次强制改密）。
- 工作台点击「进入工作区」→ 实例启动 → 打开 DSH 界面。
- 上传附件（密级 ≤ 本人密级）、建团队、后台各页可访问。
- 内网无 randomUUID 崩溃（polyfill 已注入；用 Chromium 86 验证一次）。

4.9 可选：HTTPS / 内网 DNS

HTTPS（自签，Chrome 86 可手动信任）： bash
openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \
-keyout /etc/nginx/ssl/dsh.key -out /etc/nginx/ssl/dsh.crt -subj "/CN=dsh.corp.local"

在 dsh-portal.conf 增加 listen 443 ssl; ssl_certificate ...; 并让平台前端由 https 提供。.env 中可选开启 cookie secure。

内网 DNS：dsh.corp.local -> <应用服务器IP>；无 DNS 也可用 IP 直访（两种均支持）。

4.10 运维：备份 / 恢复 / 监控

备份（每天 02:30，建议 cron）： cron 30 2 * * * /srv/dsh-platform/app/scripts/backup.sh full >> /srv/dsh-platform/logs/backup.log 2>&1

产物在 /srv/dsh-platform/backups/（db_<ts>.sql + data_<ts>.tar.gz），保留 30 天滚动。

恢复： bash /srv/dsh-platform/app/scripts/restore.sh /srv/dsh-platform/backups/data_<ts>.tar.gz /srv/dsh-platform/backups/db_<ts>.sql

监控告警（每分钟，alerts.log 兜底 + 可选 SMTP）： cron
* * * * * /srv/dsh-platform/app/scripts/monitor.sh >> /srv/dsh-platform/logs/monitor.log 2>&1

检查：Portal/Gateway/Nginx 存活（自动重启）、磁盘 >85%、推理服务健康、实例 CRASHED 超限。

日志：/srv/dsh-platform/logs/（应用日志按天轮转，保留 90 天）+ Nginx access log。

4.11 平台版本离线升级 bash
cd /opt/dsh-portal-offline-v1.1.0
BUNDLE=$(pwd) ./scripts/update.sh

update.sh：校验 manifest → backup.sh quick 备份 → 换新 app/server 与 app/web → cli.js migrate + cli.js seed → systemctl restart dsh-portal → smoke-test.js。

运行中的 DSH 实例继续跑旧版，直到回收后按 template + dsh-runtime 新版本重建（文档 11.6/11.7）。

4.12 DSH 本体升级与回滚

- 新版本 DSH 离线包 → 在联网机按附录 B 验证清单回归（反代 Host 重写、randomUUID、settings API、会话文件格式）。
- 替换 dsh-runtime/（保留上一版本目录如 dsh-runtime-v<prev>/）；update.sh 可一键切回。
- 实例数据目录（instances/{uid}/）与 DSH 程序目录物理分离；DSH 升级不触碰用户会话数据（会话格式迁移由 DSH 自身在下次启动完成，平台不直读直写会话文件）。

回滚：若新版本异常，systemctl stop dsh-portal，将 dsh-runtime-v<prev> 覆盖回 dsh-runtime，重启即可。

5. 已实现功能

| 文档章节 | 状态 | 说明 |
| FR-01 账号/认证 | ✅ | CSV 导入、工号+密码登录、scrypt 哈希、5 次锁定 15 分钟、IP 限流、强制改密、角色 |
| FR-02 门户与实例接入 | ✅ | 工作台、/api/instance/status 拉起、冷启动/排队提示、闲置回收、进入 DSH |
| FR-03 数据隔离 | ✅ | 每用户独立实例目录、进程/网络隔离；API Key 仅环境变量注入 |
| FR-04 密级体系 | ✅ | 分档可配置、上传校验 ≤ 人员密级、团队/审计可见性强制（服务端） |
| FR-05 团队工作区 | ✅ | 部门/项目团队、成员密级校验、mounts/ symlink 挂载；快照每日（见 backup.sh） |
| FR-06 附件管理 | ✅ | 类型/大小/密级校验、sha256 去重、个人配额、下载授权 |
| FR-07 内容审计 | ✅ | 会话全文(zlib) + 输出摘要 + token/耗时入库；敏感词 block/truncate/log；操作留痕 |
| FR-08 管理后台 | ✅ | 用户/团队/实例/敏感词/审计会话/日志/用量/配置/技能包 |
| FR-09 技能库 | ✅ | 管理员上传 zip（zip-slip 校验）合入 template/skills |
| NFR-02 浏览器基线 | ✅ | 前端 target es2019，browserslist: Chrome>=86，polyfill 注入 |
| NFR-09 安全 | ✅ | HttpOnly Cookie + CSRF；全部服务仅监听 127.0.0.1；dsh-gov 门禁占位 |
| NFR-10 完全离线 | ✅ | offline-pack.sh 自包含；安装/更新零联网 |
| NFR-11 DSH 升级兼容 | ✅ | 集成走配置模板/环境变量/反代/插件；dsh-adapter 唯一适配层 |
注：DSH 升级相关的 15.2 行为项（dsh --profile web 启动细节、settings./credentials. 反代 200、插件兼容性）需在 Staging 环境用真实 DSH 实测验证后固化（文档附录 B）。本代码已按文档结论落地反代 Host/Origin 重写与 polyfill。

6. 关键实现决策

- 压缩：审计 prompt_zstd 列在本地实现暂用 Node zlib（gzip）压缩，零原生依赖；替换为 zstd 只需改 src/shared/compress.js（schema 不变）。
- 单进程：Portal + Gateway + Instance Manager 同进程（文档允许，doc 11.2），简化部署；生产由 systemd 托管。
- 会话表：服务端会话表支持强制下线/锁定联动；Cookie dsh_session，HttpOnly + SameSite=Lax。
- 实例令牌：网关校验用 HMAC 签名的实例令牌，非真实推理 Key（FR-03-03）；真实 Key 仅存平台 .env（chmod 600）。
- 团队文件密级：V1 按团队整体密级管控（团队密级 = 目录密级），不做团队内逐文件密级（文档 15.3/6.5 简化项）。

7. 附录：环境变量参考

| 变量 | 默认 | 说明 |
| PORTAL_HOST | 127.0.0.1 | 应用监听地址（生产仅回环，仅 Nginx 对外） |
| PORTAL_PORT | 8080 | 应用监听端口 |
| DSH_DATA_ROOT | <repo>/data | 数据根（instances/teams/attachments/backups/logs） |
| DSH_RUNTIME_ROOT | <repo>/dsh-runtime | DSH 程序目录（bin/dsh） |
| DSH_TEMPLATE_ROOT | <repo>/template | 实例模板（AGENTS.md/技能库/插件） |
| DSH_MODE | fake（dev） | real（生产）或 fake（桩进程） |
| DB_CLIENT | pg-mem（非生产）/ pg（生产） | pg（KES/DM8）或 pg-mem（开发） |
| DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME | — | 数据库连接 |
| SESSION_TTL_HOURS | 12 | 会话滑动过期（小时） |
| LOGIN_MAX_ATTEMPTS | 5 | 连续失败锁定阈值 |
| LOGIN_LOCK_MINUTES | 15 | 锁定时长 |
| LOGIN_IP_RATE_PER_MIN | 60 | IP 级限流 |
| INSTANCE_MAX | 100 | 并发实例上限 |
| INSTANCE_IDLE_MINUTES | 30 | 闲置回收分钟 |
| INSTANCE_PORT_START/END | 20001/20999 | 实例端口池 |
| INFER_BASE_URL | http://127.0.0.1:9000 | 910B OpenAI 兼容端点 |
| INFER_API_KEY | — | 真实推理 Key（仅存 .env） |
| INFER_MODEL | deepseek-v4-flash | 默认模型 |
| INFER_CONCURRENCY_LIMIT | 64 | 全站推理并发信号量 |
| INFER_PER_USER_LIMIT | 2 | 单用户并发上限 |
| INFER_QUEUE_TIMEOUT_MS | 60000 | 排队超时（返回 429） |
| INSTANCE_TOKEN_SECRET | — | 实例令牌签名密钥（必改） |
| ADMIN_WORK_NO | admin | 引导管理员工号 |
| ADMIN_INITIAL_PASSWORD | Admin@12345 | 引导管理员初始密码 |
| WEB_DIST | <repo>/web/dist | 前端构建产物路径 |
| NODE_ENV | production | 日志级别控制 |
| LOG_LEVEL | warn（非生产）/ info（生产） | 覆盖日志级别（如 LOG_LEVEL=info 可看到启动详情） |

8. 附录：端口与目录清单

端口

| 端口 | 监听 | 用途 |
| 80/443 | 0.0.0.0 | Nginx（对外） |
| 8080 | 127.0.0.1 | Portal/Gateway |
| 20001–20999 | 127.0.0.1 | DSH 实例池 |
| 54321 | 127.0.0.1 | 数据库（默认，按实际） |

目录（DSH_DATA_ROOT=/srv/dsh-platform） text /srv/dsh-platform/ ├── app/server + app/web # 平台程序与前端 ├── runtime/node/ # Node 运行时 ├── dsh-runtime/ # DSH 本体（bin/dsh） ├── template/ # 实例模板（skills/、plugins/、AGENTS.md） ├── data/instances/{uid}/ # 每用户实例 HOME/workspace/mounts ├── data/teams/{tid}/ # 团队工作区 ├── data/attachments/{uid}/{level}/ ├── data/backups/ # 备份 ├── data/logs/ # 应用日志 + alerts.log └── .env # 平台密钥（chmod 600）

9. 常见问题 / 注意

- Windows 下 mount symlink 报 EPERM：属预期（Windows 受限）。Linux 生产环境正常。测试中已 try/catch 忽略。
- inject 与 reply.hijack()：Fastify 的 app.inject 对 hijack 的流式响应支持不完整，因此流式 SSE 端点请用真实 HTTP 验证；集成测试改用非流式路径，敏感词扫描器用单测覆盖（见 test/smoke.test.js）。
- 实例启动失败 / 端口被占：检查 INSTANCE_PORT_START/END 是否与其它服务冲突；查看 logs/ 与实例的 stop_reason。
- 数据库插入报「relation does not exist」：确认 db/migrations 已执行（cli.js migrate），且 DB_* 指向正确的库。
- 浏览器白屏：确认终端 Chromium ≥ 86；否则按附录 A 升级；常见缺失 API 的 polyfill 已注入。
- 推理排队：高峰时段排队是预期行为，公告中已说明；可调 INFER_CONCURRENCY_LIMIT、INFER_PER_USER_LIMIT。
- 浏览器兼容上线前置：需按文档附录 A 摸底，确保全员 Chromium ≥ 86。