DCTS/docs/deployment.md

DCTS 部署与运维指南 (Deployment & Operations Guide)

介绍如何在单机或跨机分布式 Linux 集群环境下编译、配置、部署与运维 DCTS 服务端与 Worker 计算节点。

---

1. 部署架构概览

DCTS 计算节点无复杂系统依赖，仅需网络能访问 Master 的 HTTP 端口。

[ Master 服务端 ] (拥有固定 IP / 域名, 如 http://192.168.1.100:8090)
   ├── dcts_server
   ├── data/dcts.db & data/dcts_queue.db
   └── data/seeds/ 集中种子仓库（node 上报/导入的收敛种子 .7+conv.json，供远程 node 下载热启动）
        ▲
        │ HTTP / REST (8090)
  ┌─────┴───────────────┬──────────────────────┐
[ Worker 节点 A ]     [ Worker 节点 B ]      [ Worker 节点 C ]
  (16 Cores)            (32 Cores)             (64 Cores)
  dcts_node             dcts_node              dcts_node

---

2. 环境准备与源码编译 (Build & Compilation)

2.1 系统依赖准备

编译与运行 DCTS 需要以下 Linux 基础环境：

• Rust Toolchain: Rust 1.75+（使用 rustup 安装）
• Fortran 编译器与工具: gfortran, gcc, make（用于运行 TLUSTY/SYNSPEC 物理引擎底座）

在 Ubuntu/Debian 上安装基础依赖：

sudo apt-get update
sudo apt-get install -y build-essential gfortran pkg-config libssl-dev

2.2 源码编译说明

DCTS 采用 Cargo Workspace 组织项目代码，包含 server 和 node 两个核心二进制包。

开发调试编译 (Debug Mode)

编译速度快，包含调优断言与详细日志：

# 编译整个 Workspace
cargo build

# 仅编译服务端
cargo build -p server

# 仅编译 Worker 计算节点
cargo build -p node

编译产物位于 target/debug/server (或 dcts_server) 和 target/debug/node (或 dcts_node)。

生产性能编译 (Release Mode - 推荐)

进行全量 LLVM 编译优化，物理计算与网络吞吐效率最高：

# 编译 Workspace 下所有组件的全量 Release 二进制
cargo build --release

编译产物位于 target/release/server 与 target/release/node。

2.3 Fortran 物理引擎底层二进制编译 (TLUSTY & SYNSPEC)

DCTS 运行时所依赖的物理计算底座二进制文件 assets/tlusty_static 与 assets/synspec_static 是使用 gfortran 编译器对 TLUSTY 和 SYNSPEC 的 FORTRAN 原生代码进行优化编译生成的。

1. 编译 TLUSTY 恒星大气结构引擎 (assets/tlusty_static)

• 源码位置: tlusty/
  • 主程序文件: tlusty208.f
  • 依赖包含模块: BASICS.FOR, IMPLIC.FOR, ITERAT.FOR, ALIPAR.FOR, ATOMIC.FOR, MODELQ.FOR, ODFPAR.FOR, ARRAY1.FOR
• 标准编译命令:

  cd /home/fmq/program/tlusty/tl208-s54/tlusty
  gfortran -fno-automatic -O3 -o ../dcts/assets/tlusty_static tlusty208.f
  

• 大内存寻址编译选项 (推荐超大能级网格使用):

  gfortran -fno-automatic -mcmodel=large -O3 -o ../dcts/assets/tlusty_static tlusty208.f
  

2. 编译 SYNSPEC 理论光谱合成引擎 (assets/synspec_static)

• 源码位置: synspec/
  • 主程序文件: synspec54.f
  • 依赖包含模块: PARAMS.FOR, MODELP.FOR, LINDAT.FOR, OPTPAR.FOR, SYNTHP.FOR, WINCOM.FOR
• 标准编译命令:

  cd /home/fmq/program/tlusty/tl208-s54/synspec
  gfortran -fno-automatic -O3 -o ../dcts/assets/synspec_static synspec54.f
  

• 大内存寻址编译选项:

  gfortran -fno-automatic -mcmodel=large -O3 -o ../dcts/assets/synspec_static synspec54.f
  

关键编译选项说明:

• -fno-automatic: 禁用局部变量的自动栈分配（强制将局部变量保存在静态内存区）。这是保证传统 FORTRAN 77 程序正常运行的关键参数，防止大型局部数组造成栈溢出（Stack Overflow）或段错误（Segmentation Fault）。
• -O3: 开启全量 LLVM/GCC 代码优化，极大加快完全线性化/加速 Lambda 迭代（CL/ALI）及辐射转移方程形式解的计算速度。
• -mcmodel=large: 当模型数组与数据段超越 2GB 寻址限制时，允许可执行文件使用 64 位大内存寻址模式。

---

3. 配置文件与环境变量 (.env)

主程序与计算节点均支持在项目根目录或运行目录下自动加载 .env 配置文件。

3.1 服务端环境变量表 (server)

环境变量名	默认值	说明
DCTS_PORT	8090	服务端 HTTP REST API 监听端口
DCTS_DB_PATH	data/dcts.db	主 SQLite 数据库文件路径（存放节点、网格点及种子记录）
DCTS_QUEUE_DB_PATH	data/dcts_queue.db	任务队列 SQLite 数据库文件路径
DCTS_SEEDS_DIR	data/seeds	server 端种子库目录（收敛种子 .7+conv.json，供远程 node 下载热启动，永不清理）
DCTS_BACKUP_DIR	data/backups	数据库自动/手动备份输出目录
DCTS_ADMIN_TOKEN	空	管理员控制台与敏感 API 鉴权令牌
DCTS_AUTH_TOKEN	空	旧版全局令牌（兼容回退为 Admin 凭据，建议迁移到 DCTS_ADMIN_TOKEN）
DCTS_AUTH_DISABLE	false	应急开发参数：设置为1 或 true 时跳过鉴权（仅本地调试，切勿生产）
DCTS_STALE_SEC	21600	任务运行超时重新放回队列的时间上限（秒）。默认 6 小时，约为单任务默认超时（7200s）的 3 倍缓冲，避免接近 timeout 的任务在上报前被重投
DCTS_NODE_STALE_SEC	60	判定 Worker 节点离线的心跳超时时间（秒）

3.2 Worker 节点环境变量表 (node)

环境变量名	默认值	说明
DCTS_SERVER_URL	http://127.0.0.1:8090	目标 Master 服务端 API 访问地址
DCTS_NODE_ID	自动生成 UUID	节点唯一标识（可手动指定固定值如node-node01）
DCTS_MAX_SLOTS	4	本地 Worker 节点的并发计算 Slot 槽位数
DCTS_RUNTIME_DIR	data/runtime	本地 TLUSTY/SYNSPEC 可执行程序及物理谱线数据存放目录
DCTS_WORK_DIR	data/work	本地计算沙盒工作目录
DCTS_RESULT_DIR	data/result	node 端完整计算结果归档目录（光谱/连续谱/各阶段大气快照等全部产物）。永久保留，无 LRU 淘汰（2026-08-02 撤销旧 MAX_RESULT_MODELS=200 上限，避免科学产物被淘汰丢失）。旧名 DCTS_ARCHIVE_DIR 向后兼容
DCTS_HEARTBEAT_SEC	15	向服务端发送心跳报告的时间间隔（秒）

两目录分工（重要，避免混淆）：

• data/seeds/（server 端，DCTS_SEEDS_DIR）：种子库。只存最小集 conv.json + <name>.7，供 download_seed 端点给远程 node 热启动下载。永不清理（种子是 SeedStep 必需资源，删除会导致已收敛点重算）。
• data/result/（node 端，DCTS_RESULT_DIR）：完整计算结果归档。存全部科学产物（.spec/.cont/.iden/.7/.bfac/.emflux/各阶段快照/日志），供本地留档/排错。永久保留，无 LRU 淘汰（2026-08-02 撤销 LRU 上限）。

多机部署下两者物理分离：seeds 在 server 机、result 在各 node 机。单机部署下都挂在 ./data 下。

注：Worker 节点无需配置任何鉴权令牌。节点启动后免凭据提交注册申请，由管理员在 Dashboard 审批后自动下发专属 token（持久化到 runtime/.node_token）。

---

4. 启动与运行方式 (Running Modes)

根据使用场景，支持以下三种运行方式：

4.1 方式一：使用 Cargo 直接开发运行 (cargo run)

适合本地开发、调试与快速验证。

• 启动 Master 服务端:

  cargo run -p server
  # 或使用 release 模式
  cargo run --release -p server
  

• 启动 Worker 计算节点 (在另一终端):

  cargo run -p node
  # 或使用 release 模式
  cargo run --release -p node
  

4.2 方式二：二进制文件直接运行 (Direct Binary Execution)

适合简易命令行部署或手动后台运行。

1. 进入编译好的产物目录或将二进制分发至各节点：

   cd /home/fmq/program/tlusty/tl208-s54/dcts
   

2. 启动 Master 服务端:

   ./target/release/server
   

3. 启动 Worker 计算节点:

   ./target/release/node
   

4.3 方式三：一键统一部署自动化控制台脚本 (全栈强烈推荐)

系统整合并提供了覆盖全业务场景的一键全自动化部署与运维治理脚本 scripts/deploy.sh。能够自适应处理本地自部署与异地全自动化编译、推送及拉起的集群管线要求。

该部署管理框架支持互动式三步精细向导 (3-Step Wizard) 与 自动化长命令行快捷免打扰调度。 您可以根据具体场景灵活运用以下策略组：

安装环境	技术引擎	适用场景说明	推荐自动化直呼执行命令
本地 (Local)	Docker Compose	单机联调或微服务生态整装秒启动	./scripts/deploy.sh -e local -b compose -r all
远程 (Remote)	Docker Compose	面对严苛依赖的机群打散化打包发布与全动态差分更新	./scripts/deploy.sh -e remote -b compose -r all
本地 (Local)	Systemd 原生	宿主无虚拟化损耗的高并发物理机运行（具备自启提权判定）	sudo ./scripts/deploy.sh -e local -b systemd -r all
远程 (Remote)	Systemd 原生	主端向分站超算节点无界穿梭远抛落地与托管后台注册	./scripts/deploy.sh -e remote -b systemd -r node

1. 交互式多重导航进站直奔体验

在宿主机或者编译主工作区，以最简洁无参数方式执行即唤醒主线指引，全程遵循人性化三层连贯设计选项：

./scripts/deploy.sh

1. 第一步 (环境定位)：指明需要作用于本地主机还是经 SSH 高速管道传输并管理远端机房控制端；
2. 第二步 (底层引擎)：指明借助 Docker Compose 容器微服务架构（绝佳无冲突隔离）或是注入原生主机执行的 Systemd 系统级常驻服务（也含双端优雅拆毁卸载/一键强停命令分支）；
3. 第三步 (目标角色)：选定全部服务 [All: Server + Node]、仅运维主控服务端 [Server] 或 仅挂扣物理分流算力池计算 Worker 节点 [Node]。

2. 系统服务与集群清收降解管理 (去除与关停)

无论是系统底层的 Systemd 表项或者是持续处于自运行圈范围内部的 Compose 集群容器套，随时均可指派拆除动作清除干净：

# 卸载或清除对应部署架构，例如卸载本地所有的 systemd 原生守护任务链
./scripts/deploy.sh remove -e local -b systemd -r all

# 也可随时直接带单 remove 操作前缀命令进行安全降解
./scripts/deploy.sh remove -e remote -b compose -r server

3. 守护进程实时勘侦管控技巧 (当直接采用 Systemd 环境时)

# 检查服务端 / Node 计算分核任务运行常态与生存心跳
sudo systemctl status dcts-server
sudo systemctl status dcts-node

# 精细翻查计算现场时变工作流水轴、迭代误差跟溯及实时运行输出
tail -f data/logs/dcts_server.*.log
tail -f data/logs/dcts_node.*.log

4.4 方式四：Docker / Docker Compose 标准纯手工控制容器联调（可选方案）

系统由专门精简构筑过的 Dockerfile.server 和 Dockerfile.node 作为构建基础，默认通过只读载入 assets 并以多路复用方式提供极致并发计算生态体系：

# 快速于本机执行容器冷启聚合与并跑
docker compose up -d --build

启动之后访问对口暴露监控 HTTP Dashboard 地址（常规默认指引定位至端口 8090），立即获尽实时拓扑状态曲线！

---

5. 工作流执行流程示例

1. 检查节点注册状态:

   curl -X GET http://localhost:8090/api/status
   

2. 启动默认网格工作流:

   curl -X POST http://localhost:8090/api/workflows/sdB_cno/start
   

3. 查询工作流详情:

   curl -X GET http://localhost:8090/api/workflows/sdB_cno
   

---

6. 日志管理与集群监控

• 轮转日志: 默认在运行目录的 data/logs/ 目录下按天自动轮转生成，如：
  • 服务端日志: data/logs/dcts_server.2026-07-27.log
  • 节点端日志: data/logs/dcts_node.2026-07-27.log
• 集群状态接口: 通过 GET /api/status 实时监控集群在线节点列表、每个节点的 CPU/内存使用率、活动 Slot 数、在线节点总数及系统资源槽位总数。