DCTS/docs/architecture.md

DCTS 系统架构 (System Architecture)

介绍 DCTS (Distributed Computing TLUSTY/SYNSPEC) 的整体设计架构、Master-Worker 拓扑结构、任务生命周期流转及容错机制。

---

1. 架构拓扑 (Topology)

DCTS 采用中心化控制、分布式离散执行 (Master-Worker) 的拓扑设计：

flowchart TB
    subgraph Master Node ["Master 服务端 (server)"]
        API["Axum HTTP REST API"]
        DB[(主数据库 dcts.db)]
        MQ[(任务队列 dcts_queue.db)]
        Scheduler["Grid Scheduler 网格调度器"]
        SeedsStorage["本地种子库 results/*.7"]
        
        API <--> DB
        API <--> MQ
        Scheduler --> MQ
        Scheduler --> DB
    end

    subgraph Compute Nodes ["分布式计算节点集群 (node)"]
        Worker1["Worker 节点 1 (Node Daemon)"]
        Worker2["Worker 节点 2 (Node Daemon)"]
        WorkerN["Worker 节点 N (Node Daemon)"]
    end

    Worker1 -- "1. 心跳/抢占任务 (Claim)" --> API
    Worker1 -- "2. 下载种子/基础数据" --> API
    Worker1 -- "3. 汇报结果/上传 .7 大气" --> API

    Worker2 -- "HTTP REST / Bearer Auth" --> API
    WorkerN -- "HTTP REST / Bearer Auth" --> API

    API --> SeedsStorage

---

2. 核心组件职责

2.1 Master 服务端 (server & Web dashboard)

• 工作流与多任务隔离：支持多工作流并发隔离运行（grid_points 与 task_queue 增加 workflow_name 复合唯一索引），调度与重置操作严格隔离在单工作流作用域内。支持旧版 SQLite 数据库启动时无缝平滑迁移。
• 安全中间件与 RBAC：基于角色访问控制 (Admin / Node / Public) 划分 API 权限，内嵌 Bearer Token 校验、Governor / 漏桶算法限流中间件与 CORS 跨域控制，防御侧信道攻击与暴力破解。
• 节点凭据生命周期管理：支持 Worker 节点注册申请、管理员审批授权、Token 吊销与重新颁发全生命周期管理。
• 任务调度与分配：通过 mq 队列管理任务生命周期，响应 Worker 的 Claim 请求分配就绪任务。
• 状态维护与心跳监测：后台离线检测线程定期标记超时未心跳的节点为 offline，并能将僵挂在超时节点上的任务自动回收到队列中（Requeue）。
• ESM 模块化 Web 看板：前端采用 ESM 模块解耦设计（state.js, api.js, components/），支持节点凭据管理、工作流控制与全局 Toast 通知。

2.2 Worker 计算节点 (node)

• 弹性扩容与身份标识：DCTS_NODE_ID 未指定或为空时，自动生成基于随机 UUID 的节点 ID（node-<uuid>），原生支持 docker compose --scale node=N 动态横向扩展多个 Worker 容器。
• 环境自适应预热 (Bootstrap)：启动时核对本地 ./runtime 运行依赖，缺失时自动向 Master 拉取可执行文件与二进制数据。
• 任务抢占与执行 (Claim & Execute)：根据并发配置轮询抢占任务，调用 common 启动子进程链（tlusty / synspec）。
• 种子检索与回传 (Seed Sync)：计算成功后将收敛的大气结构文件（.7）与状态 JSON 汇报回服务端。

---

3. 任务生命周期 (Task Lifecycle)

网格计算点从创建到完成的状态流转如下图所示：

stateDiagram-v2
    [*] --> Pending : 工作流注册生成网格点
    Pending --> Running : Worker 成功 Claim 抢占
    
    state Running {
        [*] --> ExecutingChain
        ExecutingChain --> ColdStartChain : 默认冷启动 (lte->nc->nl)
        ColdStartChain --> Synspec : 物理收敛
        ColdStartChain --> SeedStepChain : 冷启动发散且有可邻近种子
        SeedStepChain --> Synspec : 热启动收敛
    }

    Running --> Completed : 计算成功 & 上传 .7 产物
    Running --> Pending : Worker 节点心跳超时/主动释放 (Requeue)
    Running --> Failed : 重试次数达到上限 / 彻底发散

    Completed --> [*]
    Failed --> [*]

---

4. 容错与高可用设计 (Fault Tolerance)

1. 分布式无状态 Worker & 上报阶梯退避：Worker 节点不保存持久运行控制状态，异常宕机不会损坏主数据集。计算结果向 Master 上报时，具备多达 8 次指数阶梯容灾回退（最大间隔 60 秒，覆盖超 2 分钟断断连长窗），稳健保障长时间高密物理算单不受瞬时组网闪断或服务端短时上线切换干预。
2. 零文件扫描与连接并发缩流：底层任务分批取配、排队清洗与邻接优化（Seed-Stepping）全链线依赖常驻内存的 SQlite 主从精算并调优收敛连接池配置（主库=8，队列=4 减免本地排他写冲突并发挂断）；去除了历史残存的高损及同步阻塞磁盘遍历 API，在确保零卡死响应的前提下提升查询搜索效力。
3. 任务超时与流控平稳保护 (Stale & Requeue)：服务端后台定期向已超时死挂的 Running （默认 >1800 秒）作业予以强退回转为 Pending；此外当操作维护员发起暂停或终止工作流行为时，将仅平滑洗退待调 Queued 项，悉心保育在途已投的 Worker 数值演算完整出计算归表，防假命题竞合。
4. 多级退避与种子隔离：若某点冷启动发散，自动隔离失败现场，依靠数据库记录寻找欧氏空间距离最匹配的热启动合拢 .7 气象序列；即便遇到底层强硬大步发散也不产生干扰并留存物理运行根系以便溯源。