二进制方式部署（systemd）

适用于不允许运行容器，或要求以主机进程方式纳管服务的环境。服务程序 server 是预编译的独立可执行文件，部署与运行都不需要源代码，也不需要安装任何语言运行时；只需随包附带维护后台静态文件、两个工作进程文件与语音识别引擎。

前置：先完成部署总览第 2–3 节的前置条件与部署前规划。

1. 交付包内容

程序包 dathor-server-<版本>-linux-<架构>.tar.gz 解压后包含：

文件 / 目录	说明	必需
`server`	服务端主程序，含 API 与维护后台路由	✅
`admin/`	维护后台静态文件	✅
`artifact-parser-worker.js`	附件解析工作进程文件	✅
`datasource-sqlite-worker.js`	数据源工作进程文件	✅
`stt-engine-go`	语音识别引擎程序	启用服务端语音识别时必需
`lib/`	语音识别引擎依赖的动态库	启用服务端语音识别时必需

目录结构约束（部署失败的最常见原因）

admin/ 必须位于服务的工作目录下；

两个 *-worker.js 必须与 server 位于同一目录；

不要把上述文件拆分到不同目录，按原样整体解压即可。

包的架构必须与目标主机一致（uname -m 确认 x86_64 或 aarch64）。

2. 主机准备

2.1 系统依赖

# Debian / Ubuntu
sudo apt-get update
sudo apt-get install -y ca-certificates libstdc++6 libgomp1

# RHEL / Rocky
sudo dnf install -y ca-certificates libstdc++ libgomp

2.2 服务账号与目录

sudo groupadd --system dathor
sudo useradd --system --gid dathor --no-create-home --home-dir /opt/dathor \
  --shell /usr/sbin/nologin dathor

sudo mkdir -p /opt/dathor
sudo tar xzf dathor-server-<版本>-linux-<架构>.tar.gz -C /opt/dathor
sudo mkdir -p /opt/dathor/data
sudo chown -R dathor:dathor /opt/dathor
sudo chmod 0700 /opt/dathor/data

最终目录结构：

/opt/dathor/
├── server                        # 主程序
├── admin/                        # 维护后台静态文件
├── artifact-parser-worker.js
├── datasource-sqlite-worker.js
├── stt-engine-go                 # 启用语音识别时
├── lib/                          # 启用语音识别时
├── data/                         # 头像、附件、语音模型（持久数据）
└── dathor.env                    # 环境变量文件（下一节创建）

2.3 PostgreSQL

准备 PostgreSQL 16 及以上的数据库与账号，账号需具备建表与结构迁移权限：

CREATE USER dathor WITH PASSWORD '<强密码>';
CREATE DATABASE dathor OWNER dathor;

建议数据库仅监听内网地址，并限制来源为服务主机。

3. 环境变量文件

sudo tee /opt/dathor/dathor.env >/dev/null <<'EOF'
NODE_ENV=production
HOST=127.0.0.1
PORT=3000

# 对外 HTTPS origin，必须与桌面端填写的地址完全一致
BASE_URL=https://dathor.example.com

DATABASE_URL=postgres://dathor:<密码>@127.0.0.1:5432/dathor

# 5 个互不相同的随机密钥，用 openssl rand -hex 32 分别生成
JWT_SECRET=
VAULT_MASTER_KEY=
AI_PROVIDER_SECRET_KEY=
STT_SECRET_KEY=
ARTIFACT_SIGNING_KEY=

# 初始管理员，仅用户表为空时生效
ADMIN_INITIAL_USERNAME=admin
ADMIN_INITIAL_PASSWORD=

# 数据目录
AVATARS_DIR=/opt/dathor/data/avatars

# 语音识别；不启用时改为 STT_GO_ENGINE_MODE=disabled 并删除以下各行
STT_GO_ENGINE_MODE=managed
STT_GO_ENGINE_BINARY=/opt/dathor/stt-engine-go
STT_GO_ENGINE_HOST=127.0.0.1
STT_GO_ENGINE_PORT=38080
STT_MODEL_DIR=/opt/dathor/data/stt-models
STT_MODEL_VERSION=sense-voice-small-v1
EOF

sudo chown root:dathor /opt/dathor/dathor.env
sudo chmod 640 /opt/dathor/dathor.env

STT_GO_ENGINE_BINARY 必须写绝对路径，否则语音识别引擎无法启动。完整变量清单见部署总览附录 A。

4. systemd 服务

sudo tee /etc/systemd/system/dathor.service >/dev/null <<'EOF'
[Unit]
Description=Dathor Enterprise Service
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple
User=dathor
Group=dathor
WorkingDirectory=/opt/dathor
EnvironmentFile=/opt/dathor/dathor.env
Environment=HOME=/tmp
Environment=LD_LIBRARY_PATH=/opt/dathor/lib
ExecStart=/opt/dathor/server
Restart=on-failure
RestartSec=5s
KillSignal=SIGTERM
TimeoutStopSec=30s

# 最小权限加固
NoNewPrivileges=true
PrivateTmp=true
PrivateDevices=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
ReadWritePaths=/opt/dathor/data
RestrictSUIDSGID=true
RestrictRealtime=true
LockPersonality=true
CapabilityBoundingSet=

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now dathor
sudo systemctl status dathor
sudo journalctl -u dathor -f

WorkingDirectory=/opt/dathor 与 LD_LIBRARY_PATH=/opt/dathor/lib 不可省略：前者决定维护后台静态文件能否被找到，后者决定语音识别引擎能否加载动态库。

验证：

curl -fsS http://127.0.0.1:3000/health/live
curl -fsS http://127.0.0.1:3000/health/ready    # 200 表示数据库已连通

首次启动会自动执行数据库迁移并创建初始管理员账号。

5. TLS 反向代理

服务只监听 127.0.0.1:3000，必须由前置反向代理终止 TLS。Nginx 示例见 docker.md 第 5 节，两种部署方式配置一致。

6. 语音模型文件（可选）

sudo -u dathor mkdir -p /opt/dathor/data/stt-models/sense-voice-small-v1
# 放入 sense-voice.onnx 与 tokens.txt
sudo chown -R dathor:dathor /opt/dathor/data/stt-models
sudo systemctl restart dathor

目录名需与 STT_MODEL_VERSION 一致。

7. 升级

# 1. 先备份（第 8 节）
sudo systemctl stop dathor

# 2. 保留 data/ 与 dathor.env，替换程序文件
sudo mv /opt/dathor/admin /opt/dathor/admin.old
sudo tar xzf dathor-server-<新版本>-linux-<架构>.tar.gz -C /opt/dathor
sudo chown -R dathor:dathor /opt/dathor

# 3. 启动并验证
sudo systemctl start dathor
sudo journalctl -u dathor -n 100
curl -fsS http://127.0.0.1:3000/health/ready

# 4. 验证通过后清理
sudo rm -rf /opt/dathor/admin.old

先移走旧 admin/ 目录可避免新旧静态资源混杂。数据库迁移在启动时自动执行且不可回退，务必先备份。

8. 备份

# 数据库
pg_dump -U dathor -h 127.0.0.1 dathor > dathor-$(date +%F).sql

# 数据目录
sudo tar czf dathor-data-$(date +%F).tar.gz -C /opt/dathor data

另需在密钥管理系统留存 dathor.env 中的 5 个密钥；丢失 VAULT_MASTER_KEY、AI_PROVIDER_SECRET_KEY、STT_SECRET_KEY 会导致对应密文永久不可解密。

9. 二进制部署专有排查

现象	原因与处理
`/admin` 返回 503 并提示后台未构建	工作目录下缺少 `admin/`；确认 `WorkingDirectory=/opt/dathor` 且 `admin/index.html` 存在
附件解析或数据源功能失败	两个 `*-worker.js` 未与 `server` 放在同一目录
语音识别启动超时	`STT_GO_ENGINE_BINARY` 路径错误，或未设置 `LD_LIBRARY_PATH`
语音引擎报找不到 `.so`	确认 `lib/` 目录随包解压，且 `LD_LIBRARY_PATH=/opt/dathor/lib`
头像或附件写入失败	`/opt/dathor/data` 属主不是 `dathor`，或 systemd `ReadWritePaths` 未包含该目录
服务反复重启	`journalctl -u dathor -n 200` 查看启动校验错误（密钥、`BASE_URL`、初始管理员密码）

通用排查见部署总览第 9 节。

完成部署后回到部署总览第 5 节执行首次配置与授权证书上传。