fmq/DCTS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1bfa240cb09f00715f1b1186512c3d636d65a8bc
DCTS/README.md
T
fmq 1bfa240cb0 feat(all): 源精度命名体系、工作流可观测台、节点停用管理与白名单归档 
核心变更：

  1. GridAxisValue 源精度命名
     - 新增 GridAxisValue 类型，携带 f64 数值 + YAML 源书写文本（Deref 透明兼容算术）
     - config.rs 绕过 serde_yaml 归一化，逐 token 捕获轴值原文（logg: 5.0 → g5.0）
     - runner/executor/scheduler 全链路改用 DB TEXT 列权威 point_name，
       修复 REAL 列回读丢精度导致的 model_name 错配

  2. 工作流执行可观测台
     - 新增 stats/progress/points 三组 API（进度时间序列、经验速率 ETA、
       停滞预警、逐点明细分页、收敛性热力图数据）
     - 新增 workflow_progress_snapshots 表 + tasks/grid_points 耗时列
     - runner 携带 last_iter/worst_depth/n_depths 进 conv.json
     - 前端新增 hash 路由、工作流详情页（概览/网格点/收敛分析三 Tab）、YAML 编辑器

  3. 节点停用/启用管理
     - 新增 disabled 状态 + disable/enable API；停用节点保持心跳但停止分发，
       worker 空闲待命而非退出；移除 revoke API，token 失效统一走重发覆盖；
       移除 host_name 字段

  4. 白名单结果归档
     - 新增 result_filter 模块，只归档有语义产物，丢弃 Tlusty 中间单元（~2MB/模型）
     - executor 原子写入归档 + 200 点 LRU 上限

  5. 历史数据导入
     - sync_seeds 重写为 import_results：经 /admin/import_seed 标记 converged +
       按新版命名迁移产物树

  6. 部署与目录重规划
     - data/results→seeds、data/archive→result + migrate_data_dirs.sh
     - deploy.sh 增强（SSH 复用、Profile、远程 env）；Dockerfile 瘦身

  7. 文档同步更新 api/database/architecture/deployment
2026-07-31 01:34:05 +08:00

149 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# DCTS (Distributed Computing TLUSTY/SYNSPEC)
> 基于 Rust 构建的高性能分布式恒星大气模型（TLUSTY）与合成光谱（SYNSPEC）网格计算调度系统。
---
## 💡 项目简介
**DCTS** 是专为恒星光谱计算设计的分布式计算控制系统。通过将多维度参数网格（如 Teff, log g, log He, log C, log N, log O）离散化为独立计算点，DCTS 能够在 Master 服务端统一管理任务队列与计算状态，由分布在不同物理节点上的 Worker 离散执行 4 阶段物理收敛链，实现自动化调度、种子传递、发散回退与高吞吐并行计算。
---
## 🚀 快速开始 (Quickstart)
### 1. 编译系统
```bash
cd dcts
cargo build --release
```
编译产物位于 `target/release/`：
- `server`：调度与 API 主服务端
- `node`：计算节点后台进程
- `import_results`：历史计算结果导入工具（旧版单机网格结果 → 标记已完成 + 迁移产物树）
### 2. 构建前端与启动服务端 (Master & Web Dashboard)
首先编译前端全域实时网格可视图看班：
```bash
cd dashboard && npm install && npm run build && cd ..
```
运行后端处理与管理主程序 (Master)：
```bash
./target/release/server --workflow config.yaml --port 8090
```
服务端启动后将通过分级自动绑定监听：
- **开放调配 RESTful 接口** (`/api/...`): 为算力节点群与客户调控工具开放的高速接口池。
- **实时监控分析空间**: 指向 `dashboard/dist`，使用通用现代浏览器访问 `http://127.0.0.1:8090/` 即可免额外网关无障碍视见计算态势全局状态台。
### 3. 启动计算节点 (Worker)
在 Worker 节点配置 `.env` 环境变量：
```env
DCTS_NODE_ID=node-worker-01
DCTS_SERVER_URL=http://<MASTER_IP>:8090
DCTS_MAX_SLOTS=4
```
运行节点进程：
```bash
./target/release/node
```
节点会自动加载 `.env`，与服务端握手注册、下载缺失的基础原子数据与可执行程序，并开始循环 Claim 任务执行计算。
---
## 🔐 安全与鉴权 (Security & Auth)
DCTS 采用**分层鉴权**模型，公网部署务必按下表配置凭据。
### 鉴权主体
| 主体 | 环境变量 | 用途 | 持有方式 |
| :--- | :--- | :--- | :--- |
| **Admin** | `DCTS_ADMIN_TOKEN` | Dashboard 登录、工作流 CRUD、起停计算、节点审批授权 | 人工，Dashboard 输入 |
| **Node** | _(服务端审批后自动颁发)_ | 心跳、领任务、上报、下载数据 | 节点本地 `.node_token` 文件（权限 600） |
> **兼容**：旧变量 `DCTS_AUTH_TOKEN` 仍有效，自动回退用作 Admin 凭据（建议迁移到 `DCTS_ADMIN_TOKEN`）。
### 节点注册流程（免凭据申请 + 管理员审批）
1. 节点启动时优先读取本地 `runtime/.node_token`；不存在则**免凭据**向 `/api/node/register` 提交注册申请，进入 `pending_approval` 待审批状态。
2. 管理员在 Dashboard「节点管理」面板点击【同意接入】后，服务端**颁发该节点专属 token**（仅返回一次，DB 只存 SHA-256 hash）。
3. 节点轮询 `/api/node/check_status` 取回专属 token 并持久化到 `.node_token`（权限 600）。
4. 后续所有请求携带专属 token；服务端按 token 反查 `node_id` 鉴权。
5. **重发/停用**：通过 Dashboard「节点凭据管理」面板或下方管理 API 操作。
### 节点凭据管理 API（Admin 角色）
| 方法 | 路径 | 说明 |
| :--- | :--- | :--- |
| GET | `/api/admin/nodes` | 列出全部节点及凭据状态（在线/token 有效/颁发时间） |
| POST | `/api/admin/nodes/:node_id/approve` | 同意待审批节点的接入申请并颁发 token |
| POST | `/api/admin/nodes/:node_id/reject` | 拒绝待审批节点的接入申请 |
| POST | `/api/admin/nodes/:node_id/reissue` | 重新颁发 token，返回新明文（旧 token 立即失效） |
| POST | `/api/admin/nodes/:node_id/disable` | 停用节点（保持在线但不再分发任务，可恢复） |
| POST | `/api/admin/nodes/:node_id/enable` | 重新启用被停用的节点 |
所有端点要求 Admin token（`Authorization: Bearer <DCTS_ADMIN_TOKEN>`）。被攻陷节点持有的 node token 无权访问这些端点，因此重发/停用始终是管理员主动行为。
### 公网部署清单
```bash
# 生成强随机 token
openssl rand -hex 32
```
```env
# .env（服务端配置；计算节点无需任何凭据，免凭据申请后由管理员审批授权）
DCTS_ADMIN_TOKEN=<强随机值>
```
**TLS 反代**（推荐 Caddy，自动 HTTPS）：
```bash
# 1. 编辑 Caddyfile，把 dcts.example.com 改为真实域名
# 2. 启用 public profile 拉起反代
docker compose --profile public up -d --build
# 3. 节点的 DCTS_SERVER_URL 改为 https://你的域名
```
### 默认安全策略
- **CORS**：仅允许同源或本地 Origin（localhost / 127.0.0.1 / [::1]）。
- **请求体限制**：普通 API 10MB，任务上报 256MB。
- **安全响应头**：CSP / `X-Content-Type-Options` / `X-Frame-Options` / `Referrer-Policy` 默认开启。
- **审计日志**：所有写操作（POST/PUT/DELETE）记录 `subject + method + path`（不记请求体）。
- **应急调试**：`DCTS_AUTH_DISABLE=1` 跳过全部鉴权（仅本地，切勿生产）。
---
## 🏛️ Workspace 核心模块
| Crate / Tool | 类型 | 职责说明 | 详细文档 |
| :--- | :--- | :--- | :--- |
| [`common`](crates/common/README.md) | Library | 提供底层配置解析、输入文件构造、收敛判定、子进程调用与种子匹配引擎 | [README](crates/common/README.md) |
| [`server`](crates/server/README.md) | Binary | 基于 Axum 的中央 API 服务端，负责网格生成、节点心跳、任务调度与状态持久化 | [README](crates/server/README.md) |
| [`node`](crates/node/README.md) | Binary | Worker 节点 Daemon 进程，负责任务抢占、自适应环境预热、计算链执行与产物汇报 | [README](crates/node/README.md) |
| [`mq`](crates/mq/README.md) | Library | 基于 SQLite 构建的高可靠事务型分布式任务队列引擎 | [README](crates/mq/README.md) |
| [`dashboard`](dashboard/index.html) | Web UI | 基于 Vite 与原生高交互前端语系创写的分层式恒星网格任务可观测可视化控表空间 | [说明详情](dashboard/package.json) |
| [`import_results`](tools/import_results/README.md) | Tool CLI | 历史计算结果导入工具（旧版单机网格结果 → 标记已完成 + 迁移产物树） | [README](tools/import_results/README.md) |
---
## 📚 详细文档导航 (`docs/`)
系统技术细节按以下主题组织：
- 📐 **[系统架构 (Architecture)](docs/architecture.md)**：Master-Worker 拓扑结构、任务生命周期与心跳机制。
- 🔗 **[API 参考 (API Reference)](docs/api.md)**：Axum RESTful 接口规格明细与鉴权方式。
- 💾 **[数据库设计 (Database)](docs/database.md)**：SQLite 数据表结构模式与队列状态机设计。
- ⚙️ **[物理链设计 (Design)](docs/design.md)**：4 阶段 TLUSTY/SYNSPEC 计算链、冷启动与种子步进（Seed Step）降级重试逻辑。
- 📦 **[部署运维指南 (Deployment)](docs/deployment.md)**：生产环境部署、Systemd 服务配置、安全令牌与日志管理。
- 🔧 **[故障排查 (Troubleshooting)](docs/troubleshooting.md)**：常见发散案例分析、僵死进程回收、节点断连恢复。
- 🤝 **[参与贡献 (Contributing)](docs/contributing.md)**：本地开发环境搭建、规范与测试说明。
---
## 📄 License & 联系方式
- **License**: MIT / Apache-2.0
- **Maintainers**: TLUSTY High-Performance Computing Workgroup
Reference in New Issue View Git Blame Copy Permalink