企业私有服务部署指引

面向实施工程师与客户方技术人员的服务端安装部署手册。按本文完成部署后，雷驼桌面端即可连接该服务并登录使用。

文档	用途
本文	交付物、架构、前置条件、部署前规划、方式选择、首次配置、授权、升级/备份/排错、环境变量参考
docker.md	推荐：容器方式部署（Docker Compose）
binary.md	二进制方式部署（无容器环境，或要求以主机进程纳管时使用）

首次部署预计耗时 30–60 分钟，不含 TLS 证书申请与网络审批。

0. 交付物

部署前请确认已从供应方获得：

交付物	形式	用于
服务镜像	镜像仓库地址，或离线镜像包 `dathor-server-<版本>.tar`	容器方式部署
服务程序包	`dathor-server-<版本>-linux-<架构>.tar.gz`	二进制方式部署
语音模型包（可选）	模型目录压缩包	启用服务端语音识别
授权证书签发通道	联系方式与流程	部署后换取授权证书

两种部署方式二选一，无需同时获取对应交付物。

1. 服务组成

雷驼企业私有服务是一个部署单元：单个服务进程同时提供桌面端 API、维护后台（/admin）与托管的语音识别引擎；外部依赖只有一个 PostgreSQL。

flowchart LR
  subgraph client["客户内网 / 员工终端"]
    D["雷驼桌面端"]
    B["浏览器（管理员）"]
  end

  P["TLS 反向代理<br/>Nginx / HAProxy<br/>BASE_URL 对应的 HTTPS 入口"]

  subgraph unit["雷驼企业私有服务（单个部署单元）"]
    A["服务进程<br/>API /api/*<br/>维护后台 /admin<br/>健康检查 /health/*"]
    S["语音识别引擎<br/>仅回环 127.0.0.1:38080"]
    F["数据目录<br/>头像 · 附件 · 语音模型"]
  end

  PG[("PostgreSQL 16+<br/>业务数据 · 配置 · 密文")]

  D -- HTTPS --> P
  B -- HTTPS --> P
  P --> A
  A --> S
  A --> F
  A --> PG

要点：

维护后台不是独立产品，由服务进程在 /admin 路径随包托管，不需要单独部署或单独端口。
服务进程只监听一个 HTTP 端口（默认 3000），TLS 必须由前置反向代理终止。
语音识别引擎在 managed 模式下由服务进程自动拉起，只监听回环地址，不对外暴露。
持久数据只有两处：PostgreSQL 与 数据目录（头像、附件、语音模型文件）。备份这两处即可。

2. 前置条件

项	要求	说明
操作系统	Linux x86_64 或 arm64	生产部署仅支持 Linux
CPU / 内存	建议 4 vCPU / 8 GB 起	启用服务端语音识别时内存需求更高
磁盘	建议 50 GB 起	数据库、附件、语音模型文件
PostgreSQL	16 及以上	可随容器部署一并拉起，也可使用客户已有实例
网络	员工终端可访问服务的 HTTPS 域名	局域网或内网域名均可
TLS 证书	与 `BASE_URL` 域名匹配	自签证书需在客户端接受风险，建议使用可信证书
出站访问	视所选 AI 供应商而定	使用外部大模型 API 时，服务端需能访问对应地址
镜像仓库访问	仅在线拉取镜像时需要	无外网时改用离线镜像包
授权证书	由供应方签发的 `license.json`	见第 6 节

容器方式另需 Docker Engine 24+ 与 Compose v2。

3. 部署前必须规划的三件事

3.1 对外访问地址 `BASE_URL`

BASE_URL 是权威对外访问 origin，必须与员工在桌面端填写的服务器地址、管理员浏览器访问 /admin 的地址完全一致。

生产环境必须是 HTTPS，且不带路径、查询串与凭据，例如 https://dathor.example.com。
不要先用内网 IP + HTTP 上线、后期再换域名：更换 origin 会影响管理员会话 Cookie 与已配置的客户端。
服务进程本身不做 TLS，请在前置反向代理终止 TLS，并把服务端口绑定在回环地址，避免绕过代理直连。
服务端不把代理转发头当作信任锚，BASE_URL 才是权威 origin。

3.2 独立密钥

生产环境必须显式设置 5 个互不相同的随机密钥，每个至少 32 字节：

变量	作用	更换后果
`JWT_SECRET`	签发登录 token	所有已登录会话失效（可接受）
`VAULT_MASTER_KEY`	加密 Vault 凭据	已存密文无法解密
`AI_PROVIDER_SECRET_KEY`	加密 AI 供应商 API Key 与自定义 Header	已存密文无法解密
`STT_SECRET_KEY`	加密语音识别供应商凭据	已存密文无法解密
`ARTIFACT_SIGNING_KEY`	签名附件下载地址	已签发的下载链接失效（可接受）

一次性生成：

for name in JWT_SECRET VAULT_MASTER_KEY AI_PROVIDER_SECRET_KEY STT_SECRET_KEY ARTIFACT_SIGNING_KEY; do
  printf '%s=%s\n' "$name" "$(openssl rand -hex 32)"
done

生成结果写入客户的密钥管理系统或受控凭据存储，不要提交到代码仓库或工单系统，并在服务上线前完成备份。标注”已存密文无法解密”的三个属于长期密钥，部署后不得直接替换。

3.3 初始管理员账号

服务端不含固定密码，也不会生成或打印初始密码。首次启动（用户表为空）时按以下变量创建管理员：

变量	默认值	说明
`ADMIN_INITIAL_USERNAME`	`admin`	登录名
`ADMIN_INITIAL_NAME`	同用户名	显示名
`ADMIN_INITIAL_PASSWORD`	无	必填，12–128 字符；未设置时服务启动失败

这三个变量仅在用户表为空时生效，后续修改不影响已存在的账号。首次登录后请立即在维护后台修改该密码。

4. 选择部署方式

flowchart TD
  Q{"客户环境允许运行<br/>Docker 容器？"}
  Q -- 是 --> DK["容器方式部署<br/>docker.md（推荐）"]
  Q -- 否 --> BN["二进制方式 + systemd<br/>binary.md"]
  DK --> C["共同步骤：反向代理 → 首次登录 → 上传授权证书 → 配置 AI / 语音 / 用户"]
  BN --> C

对比项	容器方式	二进制 + systemd
环境依赖	Docker Engine + Compose v2	glibc、libstdc++、libgomp
PostgreSQL	可随部署一并拉起	需客户自行提供
升级	导入新镜像后重建容器	替换程序目录后重启服务
安全加固	交付配置已内置只读根文件系统、非 root、能力裁剪	需在 systemd unit 中配置（文档已给模板）
推荐度	默认推荐	无容器环境或有主机纳管要求时使用

选定后按对应文档执行，完成后回到第 5 节。

5. 首次配置（两种方式通用）

浏览器打开 ${BASE_URL}/admin，使用 ADMIN_INITIAL_* 凭据登录。
立即修改初始管理员密码。
进入授权页面，按第 6 节上传授权证书。
配置 AI 供应商、模型与默认 Agent；未配置时桌面端 AI 能力不可用。
按需配置服务端语音识别、团队导航、侧边栏入口、Agent 工具与 AI 右键菜单模板。
创建组织架构与用户账号。
在桌面端填写 BASE_URL 作为服务器地址并登录，验证导航、AI、语音等关键路径。

桌面端首次连接会固定（pin）服务端身份公钥；若服务端身份此后发生变化（例如重建实例导致密钥重生），客户端会拒绝连接，需用户显式确认”信任新身份”。该机制用于识别连接对端，不替代 TLS。

6. 授权证书

无证书、证书过期或损坏时服务端处于未授权状态：维护后台仍可登录、桌面端仍可登录并使用本地内容，但服务端 AI、语音识别、附件等能力会被拒绝。

sequenceDiagram
  participant C as 客户方技术人员
  participant S as 雷驼服务端 /admin
  participant V as 供应方
  C->>S: 下载 public-only server-identity.json
  C->>V: 提交 public-only server-identity.json 与商业协议信息
  V->>V: 离线签发 license.json
  V-->>C: 返回 license.json
  C->>S: 在维护后台上传 license.json
  S->>S: 离线校验签名与实例绑定，应用授权策略

证书绑定到具体服务端身份，重建服务端实例后原证书失效，需要重新签发。
维护后台下载的 server-identity.json 只包含 instanceId、publicKeyPem、createdAt；不包含也不应外发服务端私钥。
证书中的启用账号上限与服务截止时间按商业协议约定；不限人数或永久授权时对应字段为空。
校验完全离线完成，服务端不需要联网，也不会因此外发数据。
授权校验属于商业交付范围控制，不是安全边界，不替代 TLS、访问控制与密钥保护。

7. 升级

阅读版本发布说明，确认是否有额外操作要求。
先备份（第 8 节）。数据库迁移为单向（forward-only），无法回退。
按所选部署方式替换服务版本并重启，见各自文档的”升级”章节。
启动后确认 /health/ready 返回 200，再抽查 /admin 与桌面端关键路径。

数据库结构迁移在服务启动时自动执行，无需手工操作。

8. 备份

必须同时备份三部分，数据库与数据目录尽量取同一时间点：

对象	内容	说明
PostgreSQL	用户、组织、导航、Vault 密文、配置、日志	用 `pg_dump` 定期全量备份
数据目录	头像、附件、语音模型文件	文件级备份
密钥	第 3.2 节的 5 个密钥	存于密钥管理系统

只恢复数据库而丢失 VAULT_MASTER_KEY / AI_PROVIDER_SECRET_KEY / STT_SECRET_KEY，对应密文将永久不可解密。

9. 常见问题排查

现象	排查方向
启动即退出并报密钥错误	5 个密钥是否都已设置、互不相同、至少 32 字节
启动即退出并报 `BASE_URL` 错误	生产环境 `BASE_URL` 必须是不含路径、查询串与凭据的 HTTPS origin
启动即退出并报初始管理员密码错误	用户表为空时必须设置 12–128 字符的 `ADMIN_INITIAL_PASSWORD`
服务不健康	`/health/live` 看进程存活，`/health/ready` 看 PostgreSQL 连通性
`/admin` 返回 404	访问的是数据库或语音引擎端口，而非服务端口
`/admin` 返回 503 并提示后台未构建	后台静态文件缺失，说明交付包不完整或部署目录结构不正确
管理员登录后立刻掉线	`BASE_URL` 与浏览器实际访问 origin 不一致，或反向代理未按 HTTPS 透传
桌面端连不上	`BASE_URL`、端口可达性、TLS 证书、客户端填写的地址
桌面端提示服务端身份变化	确认服务端是否被有意重建或重置，再显式信任新身份
AI 能力报未授权	上传有效授权证书；确认证书绑定的实例与当前服务端一致
AI 能力报配置缺失	在维护后台配置并保存 AI 供应商、模型与默认 Agent
语音识别不可用	检查语音引擎模式、模型目录与 `STT_MODEL_VERSION` 是否匹配

附录 A. 环境变量参考

两种部署方式使用同一套环境变量，未列出的保持默认即可。

基础

变量	说明	默认值
`BASE_URL`	权威对外访问 origin；生产环境必须为 HTTPS，且不含路径、查询串与凭据	—
`PORT`	服务监听端口	`3000`
`HOST`	监听地址；容器内设为 `0.0.0.0`，主机部署建议 `127.0.0.1`	`127.0.0.1`
`NODE_ENV`	生产部署设为 `production`	—
`ADMIN_ALLOWED_ORIGINS`	额外允许访问维护后台的精确 HTTPS origin，逗号分隔，不支持通配符	—
`SWAGGER_ENABLED`	暴露 `/openapi.json` 与 `/api-docs`；仅接受 `true` / `false`，UI 需访问 `cdn.jsdelivr.net`	`false`

数据存储

变量	说明	默认值
`DATABASE_URL`	PostgreSQL 连接串	`postgres://dathor:dathor@127.0.0.1:5432/dathor`
`POSTGRES_POOL_MAX`	连接池上限，按部署规模与数据库 `max_connections` 调整	`10`
`POSTGRES_IDLE_TIMEOUT_SECONDS`	空闲连接回收秒数	`30`
`POSTGRES_CONNECTION_TIMEOUT_SECONDS`	建立连接超时秒数	`15`
`AVATARS_DIR`	用户头像存储目录	`./data/avatars`

密钥（生产必填，互不相同，≥32 字节）

变量	说明
`JWT_SECRET`	登录 token 签名密钥
`VAULT_MASTER_KEY`	Vault 密文主密钥（长期密钥）
`AI_PROVIDER_SECRET_KEY`	AI 供应商凭据加密密钥（长期密钥）
`STT_SECRET_KEY`	语音识别供应商凭据加密密钥（长期密钥）
`ARTIFACT_SIGNING_KEY`	附件下载地址签名密钥

初始管理员（仅用户表为空时生效）

变量	说明	默认值
`ADMIN_INITIAL_USERNAME`	登录名	`admin`
`ADMIN_INITIAL_NAME`	显示名	同用户名
`ADMIN_INITIAL_PASSWORD`	初始密码，12–128 字符	无，必填

语音识别引擎

变量	说明	默认值
`STT_GO_ENGINE_MODE`	`managed`（服务进程自动拉起）/ `external`（外部引擎）/ `disabled`	`managed`
`STT_GO_ENGINE_HOST`	`managed` 模式监听地址	`127.0.0.1`
`STT_GO_ENGINE_PORT`	`managed` 模式监听端口	`38080`
`STT_GO_ENGINE_BINARY`	`managed` 模式引擎程序路径	见 binary.md
`STT_GO_ENGINE_EXTERNAL_URL`	`external` 模式引擎基地址	—
`STT_GO_ENGINE_TOKEN`	`external` 模式访问令牌（≥32 字节）；`managed` 模式自动生成	—
`STT_GO_ENGINE_STARTUP_TIMEOUT_MS`	引擎启动就绪超时（毫秒）	`15000`
`STT_GO_ENGINE_REQUEST_TIMEOUT_MS`	单请求超时（毫秒）	`120000`
`STT_MODEL_DIR`	语音模型根目录	`./data/stt-models`
`STT_MODEL_VERSION`	使用的模型版本目录名	`sense-voice-small-v1`

桌面端更新与日志留存

变量	说明	默认值
`DESKTOP_UPDATE_BASE_URL`	桌面端安装包根 URL；未配置则不提供更新	—
`DESKTOP_UPDATE_VERSION`	当前对外发布的最新桌面端版本号	—
`AI_USAGE_LOG_RETENTION_DAYS`	AI 用量日志留存天数	`365`
`AGENT_LOG_RETENTION_DAYS`	Agent 日志留存天数	`90`
`AUDIT_LOG_RETENTION_DAYS`	审计日志留存天数	`365`

附录 B. 健康检查与监控

路径	含义	用途
`GET /health/live`	进程存活	进程守护、容器 liveness
`GET /health/ready`	依赖就绪（PostgreSQL 可达）；未就绪返回 503	负载均衡摘挂、发布验证
`GET /admin`	维护后台入口	人工验证

建议对 /health/ready 做周期探测，连续失败即告警；同时监控 PostgreSQL 可用性与数据目录磁盘余量。