# 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/results/ 集中种子仓库与计算摘要
        ▲
        │ 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 上安装基础依赖：

```bash
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)

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

```bash
# 编译整个 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 编译优化，物理计算与网络吞吐效率最高：

```bash
# 编译 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`
* **标准编译命令**:
  ```bash
  cd /home/fmq/program/tlusty/tl208-s54/tlusty
  gfortran -fno-automatic -O3 -o ../dcts/assets/tlusty_static tlusty208.f
  ```
* **大内存寻址编译选项 (推荐超大能级网格使用)**:
  ```bash
  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`
* **标准编译命令**:
  ```bash
  cd /home/fmq/program/tlusty/tl208-s54/synspec
  gfortran -fno-automatic -O3 -o ../dcts/assets/synspec_static synspec54.f
  ```
* **大内存寻址编译选项**:
  ```bash
  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_RESULTS_DIR`    | `data/results`       | 集中种子仓库与计算总结`conv.json` 保存目录                     |
| `DCTS_AUTH_TOKEN`     | *空*                 | 服务端 API 鉴权令牌（可选，若配置则需在请求头携带 Bearer Token） |
| `DCTS_STALE_SEC`      | `1800`               | 任务运行超时重新放回队列的时间上限（秒）                         |
| `DCTS_NODE_STALE_SEC` | `120`                | 判定 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_HEARTBEAT_SEC` | `15`                    | 向服务端发送心跳报告的时间间隔（秒）                 |
| `DCTS_AUTH_TOKEN`    | *空*                    | 匹配服务端的 API 鉴权令牌                            |

---

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

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

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

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

* **启动 Master 服务端**:
  ```bash
  cargo run -p server
  # 或使用 release 模式
  cargo run --release -p server
  ```
* **启动 Worker 计算节点** (在另一终端):
  ```bash
  cargo run -p node
  # 或使用 release 模式
  cargo run --release -p node
  ```

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

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

1. 进入编译好的产物目录或将二进制分发至各节点：
   ```bash
   cd /home/fmq/program/tlusty/tl208-s54/dcts
   ```
2. **启动 Master 服务端**:
   ```bash
   ./target/release/server
   ```
3. **启动 Worker 计算节点**:
   ```bash
   ./target/release/node
   ```

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

系统整合并提供了覆盖全业务场景的一键全自动化部署与运维治理脚本 [`scripts/deploy.sh`](file:///home/fmq/program/tlusty/tl208-s54/dcts/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. 交互式多重导航进站直奔体验
在宿主机或者编译主工作区，以最简洁无参数方式执行即唤醒主线指引，全程遵循人性化三层连贯设计选项：
```bash
./scripts/deploy.sh
```
1. **第一步 (环境定位)**：指明需要作用于**本地主机**还是经 SSH 高速管道传输并管理**远端机房控制端**；
2. **第二步 (底层引擎)**：指明借助 **Docker Compose 容器微服务架构**（绝佳无冲突隔离）或是注入原生主机执行的 **Systemd 系统级常驻服务**（也含双端优雅拆毁卸载/一键强停命令分支）；
3. **第三步 (目标角色)**：选定**全部服务 [All: Server + Node]**、**仅运维主控服务端 [Server]** 或 **仅挂扣物理分流算力池计算 Worker 节点 [Node]**。

#### 2. 系统服务与集群清收降解管理 (去除与关停)
无论是系统底层的 Systemd 表项或者是持续处于自运行圈范围内部的 Compose 集群容器套，随时均可指派拆除动作清除干净：
```bash
# 卸载或清除对应部署架构，例如卸载本地所有的 systemd 原生守护任务链
./scripts/deploy.sh remove -e local -b systemd -r all

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

#### 3. 守护进程实时勘侦管控技巧 (当直接采用 Systemd 环境时)
```bash
# 检查服务端 / 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](file:///home/fmq/program/tlusty/tl208-s54/dcts/Dockerfile.server) 和 [Dockerfile.node](file:///home/fmq/program/tlusty/tl208-s54/dcts/Dockerfile.node) 作为构建基础，默认通过只读载入 `assets` 并以多路复用方式提供极致并发计算生态体系：
```bash
# 快速于本机执行容器冷启聚合与并跑
docker compose up -d --build
```
启动之后访问对口暴露监控 HTTP Dashboard 地址（常规默认指引定位至端口 `8090`），立即获尽实时拓扑状态曲线！

---

## 5. 工作流执行流程示例

1. **检查节点注册状态**:
   ```bash
   curl -X GET http://localhost:8090/api/status
   ```
2. **启动默认网格工作流**:
   ```bash
   curl -X POST http://localhost:8090/api/workflows/sdB_cno/start
   ```
3. **查询工作流详情**:
   ```bash
   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 数、在线节点总数及系统资源槽位总数。