# 部署与运维手册

> 当前基线：模拟 v0.3 保留，独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警，见 [设计](../07-history/v0.5-design.md)、[执行报告](../reports/2026-10-12-v0.5.md)。历史报告与证据保留原版本。

> v0.4新增独立链模式：[云/容器/备份恢复手册](web3-deployment.md)，[架构](../07-history/v0.4-design.md)，[本轮报告](../reports/2026-10-12-v0.4.md)。本页原命令维护模拟系统，exchangectl不能用于链任务数据库。


更新：2026-10-11，适用 v0.3.0。单实例、单核心、模拟 ETH/USDT；云主机直接运行与 Docker 容器使用同版本后端/离线工具/前端。历史发布/容器/性能证据见[v0.3 报告](../reports/2026-10-11-v0.3.md)；当前源码的所有权修复与回归见[测试完善报告](../reports/2026-10-11-test-hardening.md)。已有 v0.3 发布包与 verified 镜像属于修复前产物，尚未重新发布，不能直接当作当前源码。云实机需要用户提供服务器；本轮不声称已经上线。

## 1. 构建与发布产物

需要 Go 1.26.9、Node 22、npm 与 Linux 构建环境。go.mod 固定最低补丁版本，Docker/CI 同步；SQLite 为 CGo-free，可静态构建。先安装锁定依赖，再检查/打包：

```bash
npm --prefix frontend ci
go mod download
bash scripts/verify.sh
bash scripts/release.sh
```

发布包 `bin/releases/exchange-v0.3.0.tar.gz` 包含 exchange、exchangectl、frontend/、deploy/、SHA256SUMS、build-info.json。后端二进制嵌入 OpenAPI；前端来自同版契约，不能混装。release 脚本拒绝覆盖既有目录，且当前不支持 `--output` 或输出目录环境覆盖；已有同版本目录时需在不携带旧 bin/releases 的独立源码副本中构建，保留旧产物与摘要供审阅。build-info 记录真实工具链/依赖、engine/schema/契约摘要，没有 Git 时 commit 为 null。远程 CI 文件已提供，但需把项目推送仓库才会运行。

当前架构不要求生成 Go 路由或拆成多服务；字段契约通过生成 TS 和真实响应验证。FULL 固定，不能用“性能开关”关闭同步耐久。

## 2. 配置与资源

实际示例：[exchange.env.example](../../deploy/exchange.env.example)、[systemd](../../deploy/exchange.service)、[Compose](../../deploy/compose.yaml)、[Caddy](../../deploy/Caddyfile.example)。密码只放权限 0600 的环境文件，不复制测试管理员密码。

| 配置 | 默认/说明 |
| --- | --- |
| EXCHANGE_LISTEN_ADDR | 127.0.0.1:8080；容器 0.0.0.0:8080 |
| EXCHANGE_DATA_DIR | data；主机 /var/lib/exchange，容器 /data |
| EXCHANGE_FRONTEND_DIR | frontend/dist；发布包主机 frontend，容器 /app/frontend |
| EXCHANGE_ALLOWED_ORIGIN | 单个准确 Origin，如 https://trade.example.com；不得与访问地址混用 localhost/127.0.0.1 |
| EXCHANGE_COOKIE_SECURE | 默认 false；HTTPS 必须 true |
| EXCHANGE_ADMIN_EMAIL / PASSWORD | 首次初始化 ADMIN；无默认账号密码，重启不改已有密码，不提升 USER |
| EXCHANGE_LOCAL_ADMIN_NAME | 默认空；仅 Windows/明确回环本地模式启用账号别名与 8–72 字节初始化，云/容器不配置 |
| EXCHANGE_DIAGNOSTICS_ADDR | 空则关闭；非空必须 loopback IP，如 127.0.0.1:9090 |
| EXCHANGE_QUEUE_CAPACITY | 默认 1024，1–65536 |
| EXCHANGE_INFLIGHT_CAPACITY | 默认 2048，1–131072，直到投影提交才释放 |
| EXCHANGE_JOURNAL_BATCH_SIZE | 默认 64，1–4096，日志/投影最大批大小 |
| EXCHANGE_JOURNAL_BATCH_WAIT | 默认 1ms，0–1s，只用于日志聚批 |
| EXCHANGE_SHUTDOWN_TIMEOUT | 默认 60s，1s–5min，小于进程管理器强杀窗口 |
| EXCHANGE_HEALTH_URL | health 子命令目标，默认 http://127.0.0.1:8080/health/ready |

起步机器建议 Ubuntu 24.04、本地 SSD、2 vCPU/4GiB；这只是部署预算，不能由配置推算 TPS。实测工作区为 WSL，性能数据使用 Linux /tmp。SQLite 不放 NFS/共享对象存储，不能两个实例共享 /data；flock 是本机进程锁，不是跨主机 fencing。

## 3. 云服务器直接运行

部署目录：发布 `/opt/exchange/releases/v0.3.0`，current 指向当前版本，环境 `/etc/exchange/exchange.env`，数据 `/var/lib/exchange`，备份 `/var/backups/exchange`。专用 exchange 用户无登录权限、非 root 运行。

以下命令在目标服务器由运维执行，域名和路径使用自己的实际值：

```bash
sudo useradd --system --home /var/lib/exchange --shell /usr/sbin/nologin exchange
sudo install -d -o exchange -g exchange -m 0700 /var/lib/exchange /var/backups/exchange
sudo install -d -m 0755 /opt/exchange/releases /etc/exchange
# 将已校验发布目录复制到 /opt/exchange/releases/v0.3.0，再在该目录执行：
sha256sum -c SHA256SUMS
sudo ln -s /opt/exchange/releases/v0.3.0 /opt/exchange/current
sudo install -m 0600 deploy/exchange.env.example /etc/exchange/exchange.env
# 修改邮箱/密码/准确 Origin/路径。不要直接采用示例密码。
sudoedit /etc/exchange/exchange.env
sudo install -m 0644 deploy/exchange.service /etc/systemd/system/exchange.service
sudo systemctl daemon-reload
sudo systemctl enable --now exchange
curl --fail http://127.0.0.1:8080/health/ready
sudo journalctl -u exchange -n 100 --no-pager
```

环境中的 EXCHANGE_FRONTEND_DIR=/opt/exchange/current/frontend。只公开 443/必要的 80，SSH 仅运维来源；8080/9090 不公开。配置 Caddy 自动 TLS、准确 Origin 和 Secure Cookie，执行 `caddy validate --config <实际配置>` 后启用。需要 DNS/云安全组/实际证书可用条件；本轮没有这些外部资源，未执行。

无域名时可用 `ssh -L 8080:127.0.0.1:8080 deploy@<server-address>`；本地 HTTP 演示明确 CookieSecure=false 与对应 Origin，不能套用 HTTPS Cookie 配置。

## 4. 容器部署

标准多阶段构建复制 api/backend/cmd，生成后端与运维工具、前端，运行层为 Debian bookworm-slim；离线 Dockerfile.runtime 使用 scratch。两者均以 UID/GID 10001 非 root 运行。运行目录 /data 持久卷；rootfs 只读，/tmp tmpfs。首个卷初始化由镜像目录 ownership 保证可写，bind mount 需要自行设置 10001 所有权。

```bash
# 真实管理员密码从安全环境提供。
export EXCHANGE_ADMIN_EMAIL='admin@example.com'
read -rsp '管理员密码: ' EXCHANGE_ADMIN_PASSWORD
export EXCHANGE_ADMIN_PASSWORD
export EXCHANGE_ALLOWED_ORIGIN='http://127.0.0.1:8080'
docker compose -f deploy/compose.yaml config --quiet
docker compose -f deploy/compose.yaml up -d --build
docker compose -f deploy/compose.yaml logs --tail=100 exchange
```

在线构建仍取决于主机镜像源/Go/npm 网络。本环境用户配置的镜像源 DNS 失败，未擅改 Docker daemon；可用已验证本地产物构建运行镜像：

```bash
npm --prefix frontend run build
CGO_ENABLED=0 go build -trimpath -o bin/exchange ./cmd/server
CGO_ENABLED=0 go build -trimpath -o bin/exchangectl ./cmd/exchangectl
docker build -f Dockerfile.runtime -t exchange-demo:local .
docker compose -f deploy/compose.yaml up -d --no-build
```

scratch 镜像没有 shell/curl，HEALTHCHECK 使用 `/app/exchange health`。当前 diagnostics 在容器回环 9090，不映射公网；容器回环与宿主回环不同，宿主 curl 127.0.0.1:9090 不会自动进入容器。可用宿主受控工具通过 `nsenter -t <容器PID> -n` 采样，或已核验工具容器共享其网络命名空间；scratch 内不能 `docker exec ... curl/sh`。pprof 需受控诊断工具/方式，不为方便排错安装整套工具到生产镜像。`docker logs` 读取 JSON slog，Compose 限制日志大小、资源和停止宽限。Docker unhealthy 标记本身不会自动重启；致命运行时故障由应用监督退出。

升级保持原 volume 名称，**禁止 down -v**，不把 replicas 扩大为多个写者。镜像标签固定版本，生产可另外锁已验证 digest。当前在线 Go/Node 构建镜像使用补丁标签，Debian 运行层使用 bookworm-slim 系列标签，尚未在该网络环境验证/锁定 digest，不能把离线 runtime 构建成绩当成完整在线构建成绩。

## 5. 离线管理工具

服务停机后使用同版 exchangectl；工具与服务共享 flock，服务运行时拒绝 check/backup/rebuild。例子中的备份目标和恢复目标必须不存在，不能覆盖旧数据。

```bash
# 新目录初始化；密码只来自 EXCHANGE_ADMIN_PASSWORD，不放参数。
./exchangectl init-admin --data /var/lib/exchange --email admin@example.com
# check 会补齐正常崩溃的落后投影，并与独立重放逐表对账。
./exchangectl check --data /var/lib/exchange
./exchangectl backup --data /var/lib/exchange --backup /var/backups/exchange/20261011
# 恢复到新目录，原目录始终保留。
./exchangectl restore --backup /var/backups/exchange/20261011 --data /var/lib/exchange-restored
# 只重建可派生投影，保留原坏 views/WAL/SHM 到 views-preserved-时间戳。
./exchangectl rebuild-views --data /var/lib/exchange
```

systemd 路径需要 `sudo -u exchange`；初始化管理员时通过受控方式传入所需密码变量。systemd 的 EnvironmentFile 由管理器解析，不要直接 source 未经审阅的环境文件执行 shell 内容。check/backup/rebuild 均包含全历史重放和临时数据库，不是只读轻量命令，应预算停机时间、/tmp 空间和数据盘 staging 空间。backup 先校验/补投影、checkpoint 三库，再复制、fsync 并写 manifest；权限 0700/0600。manifest 含 dataset、engine、水位/数量/逐表摘要与数据库 SHA256。restore 先验证字节摘要/白名单，再拷贝/重放对账；不是防攻击签名，也不是在线备份。

auth.db 是权威身份/会话，不可按投影方式删除。journal.db 是权威输入，不能从 views 反推。checkpoint 不删应用 commands 历史。直接复制运行中的 .db 会遗漏 WAL，禁止这样做；云磁盘丢失仍依赖异机备份，RPO 是最近成功备份，不因 FULL 变为硬件故障 RPO=0。

容器停机维护示例：

```bash
docker compose -f deploy/compose.yaml stop exchange
# Compose run 覆盖 entrypoint，只启动离线工具，挂载相同卷。
docker compose -f deploy/compose.yaml run --rm --no-deps --entrypoint /app/exchangectl exchange check --data /data
docker compose -f deploy/compose.yaml run --rm --no-deps --entrypoint /app/exchangectl exchange backup --data /data --backup /data/backup-20261011
# 将备份复制到受限异机位置；卷内备份无法抵御整个磁盘损坏。
docker compose -f deploy/compose.yaml start exchange
```

## 6. 升级、退出与回滚

v0.3 前后端同版：users/audit 从数组改页对象，orders 仍 v0.2 页协议；旧库增加可重建审计/迁移标记，新日志 schema=1，旧 schema=0 可重放，engine_version=1 保持业务语义。升级前停唯一实例、完整备份、保留旧发布包；新程序对旧卷验证后才切换入口。

SIGTERM 主动关闭 WS、停止业务受理并排空，再等待 HTTP；投影整批成功才释放额度，最后关 DB/解锁。超时失败会记录并返回非零，已提交日志重启补齐。冷启动先完成恢复再监听 HTTP，因此准备期间通常连接拒绝；不能假称总有 ready=503 可查询。

回滚不能同时开新旧写者；先停止新接入保存最新日志。仅兼容界面/二进制时可切旧发布；恢复升级前备份可能抹掉备份后的已确认命令，必须先对账制定恢复方案。不要为“修好启动”删 journal/auth 或跳过不兼容记录。

## 7. 观测与部署验收

独立诊断端口 `/metrics` 包括阶段累计/最大耗时、已提交/执行/投影水位、队列/在途、活动订单/保留订单/幂等数、堆/GC/goroutine。max 不是 p99；业务数据集序号只在同 dataset 比较。pprof 使用标准库，默认不公开。日志为外围 JSON slog，不输出密码/会话 token/完整 payload。

每次部署验证：ready 成功 → 注册/登录 → 双账户成交/撤单 → 管理操作 → 原键确认 → 关闭/重启会话和余额保留 → 停机备份恢复到新目录 → 独占锁拒绝第二写者。查看磁盘空间/历史增长、投影 lag、容量拒绝、堆内存；本版没有日志截断/去重 TTL/自动扩容。

可重复本地/容器验证：`python3 scripts/e2e_check.py`、`python3 scripts/container_check.py`；会启动本任务独立环境。容器脚本只保留自己的已停止容器/命名卷，并生成实际资源名称和证据。云端同样执行该验收顺序，服务器未提供时不能声明云实机通过。

## 8. 手册配套与证据保存

离线步骤的文件边界与中断处理见[数据生命周期](data-lifecycle.md)，ready/401/403/未知结果/投影滞后排查见[故障排查手册](operations-runbook.md)。服务器资源、DNS/TLS、镜像在线构建、真实断电、远程 CI 均按实际环境验收，文档示例不等于已经执行。

`scripts/container_check.py` 会构建固定的 verified 标签，并将结果写入既有 evidence-v0.3/container.json；重跑前先把旧证据与镜像摘要存到独立路径，避免覆盖历史结论。本次只审阅脚本注释与配置，未重跑容器、重新打包或部署。

## Windows 本机启动路径

双击项目根目录 run-windows.cmd，脚本在 bin/windows 构建原生 exe 与独立 Windows 前端依赖，data-windows 保留数据。本地管理员模式明确限制数值回环，不在本节云/systemd/Compose 配置启用。常规部署密码下限 12 字节仍保留。见[Windows 指南](windows-local-run.md)与[实际验证](../reports/2026-10-11-windows-launcher.md)。

## v0.5 链容器与云观测

链模式采用独立镜像 exchange-web3:v0.5-local 和独立数据卷。升级前停机备份日志/投影/任务共同水位；SQLite/PG 任务显式迁移。Linux host 网络 Prometheus 可采集 127.0.0.1:9091，配置见 deploy/web3-prometheus.yml 和 web3-alerts.yml；不对外代理诊断端口。详细操作见链部署手册，云环境未实测。
