90 lines
6.6 KiB
Markdown
90 lines
6.6 KiB
Markdown
# Orbit · 星轨
|
||
|
||
Orbit 是面向多个业务项目的通用任务调度与流程编排平台，采用 **Go + MySQL + HTTP/WebSocket**。
|
||
|
||
- **Pulse · 脉动**：异步任务、定时调度、执行授权与安全重试。
|
||
- **Weave · 织流**：研发定义发布流程，管理步骤、等待、有界查询与恢复。
|
||
- 业务处理器运行在接入方 Worker 中；平台不内置行业规则。
|
||
|
||
## 当前进度
|
||
|
||
已完成 P0–P3 平台功能阶段验收：35 个数据模型、版本化迁移、凭据及范围校验、队列与任务 API、WSS 执行、独立 SDK、自动 Worker 和 [执行尝试/证据查询](docs/api/execution-history.md)。[Worker Schema](docs/api/worker-schema.md) 与真实进程强杀恢复回归已通过；[安全重试](docs/api/retries.md)、[定时计划](docs/api/schedules.md)、[运行中取消](docs/api/cancellation.md) 、[队列资源控制](docs/api/queues.md) 、[应用共享配额](docs/api/application-resources.md) 、[资源键互斥](docs/api/keyed-concurrency.md) 和 [优先级/节点公平派发](docs/api/priority-and-fairness.md) 已接入服务端和 SDK，[可靠结果订阅](docs/api/subscriptions.md) 已实现持久化核心、HTTP/WSS、管理 SDK 与示例，[消费 SDK](docs/sdk/event-consumer.md) 和 [独立 MySQL Inbox 示例](docs/examples/result-inbox.md) 已实现；[批量任务受理](docs/api/batch-tasks.md) 已提供逐项幂等、失败分类与 SDK 示例；[人工核查与重试](docs/api/task-recovery.md) 已提供带证据的管理接口、关联新任务、审计查询及运行示例；[业务键与时间范围查询](docs/api/task-queries.md) 已提供过滤、分页与SDK场景；[任务来源查询](docs/api/task-source.md) 已提供人工重试父任务、计划触发记录与固定版本；[业务事务Outbox](docs/examples/task-outbox.md) 已提供独立业务库、稳定提交身份、发送恢复与CLI；[相对延迟执行](docs/examples/delayed-task.md)已提供数据库计时及原请求恢复；完整范围核对见[P3验收](docs/reports/phase-3.md)，流程引擎与生产验证按 [持续开发计划](docs/08-development-plan.md) 继续实现。
|
||
|
||
P4已实现[流程定义与不可变版本发布](docs/api/workflow-definitions.md)、[结构版本1](docs/api/workflow-definition-format.md)及[SDK发布例子](docs/examples/workflow-definition.md)。[有限步骤决策器与内部结果交付](docs/10-workflow-engine-core.md)已实现；已补[实例受理及首批工作存储](docs/11-workflow-admission.md)。[结果消费、顺序/分支/并行推进及根检查点接续](docs/12-workflow-runtime.md)已接入后台运行器。持久化等待、后续查询轮次、失败结清及实例公共API/SDK继续开发，发布定义不会启动任务。
|
||
|
||
数据库禁止外键，关联一致性通过服务端事务校验，索引、唯一约束和 CHECK 保留；readiness 同时检查迁移及零外键要求。这不表示完整平台已具备生产服务能力。验证证据见 [P0](docs/reports/phase-0.md)、[P1](docs/reports/phase-1.md)、[P2 阶段验收](docs/reports/phase-2.md)、[安全重试](docs/reports/phase-3-safe-retry.md)、[计划调度](docs/reports/phase-3-schedules.md)、[取消与无外键回归](docs/reports/phase-3-cancellation.md) 及 [队列资源回归](docs/reports/phase-3-queue-resources.md)。
|
||
|
||
## 目录
|
||
|
||
```text
|
||
cmd/orbit/ 基础 HTTP 服务入口
|
||
cmd/orbit-migrate/ 独立数据库迁移命令
|
||
cmd/orbit-admin/ 受控初始化与私密凭据交付
|
||
model/ 公共 ID、JSON、摘要与记录原语
|
||
platform/model/ 应用、命名空间、幂等、事件和审计
|
||
platform/auth/ 凭据格式与动作/队列授权范围
|
||
pulse/model/ 任务、尝试、队列、计划和执行许可
|
||
pulse/service/ 任务与队列应用契约、输入校验
|
||
pulse/worker/ 会话、开始、续租、结果和恢复契约
|
||
pulse/retry/ 冻结策略、有限退避与未知效果决策
|
||
pulse/schedule/ Cron/间隔、漏跑、版本及计划接口
|
||
internal/timezone/ 随计划冻结的内置时区数据快照
|
||
weave/model/ 定义、实例、步骤、信号和查询轮次
|
||
weave/definition/ 有限结构/类型校验与定义发布契约
|
||
weave/engine/ 不可变规则的有限步骤决策与精确结果映射
|
||
weave/instance/ 内部实例受理/查询契约，公共运行API继续开发
|
||
internal/config/ 配置校验
|
||
internal/storage/mysql/ 连接、事务、迁移及集成测试
|
||
internal/transport/httpserver/ HTTP 接入
|
||
sdk/go/ 独立 Go SDK module 与示例
|
||
scripts/ 可复现的回归工具
|
||
docs/ 设计、接口、SDK、场景与验证报告
|
||
```
|
||
|
||
## 本地运行
|
||
|
||
要求 Go 1.27.1、MySQL 8.4+。先准备专用数据库和凭据，通过环境变量注入；程序不会自动读取 `.env` 文件。
|
||
|
||
```sh
|
||
export ORBIT_MYSQL_DSN='user:password@tcp(127.0.0.1:3306)/orbit'
|
||
export ORBIT_HTTP_ADDR='127.0.0.1:8080'
|
||
go run ./cmd/orbit-migrate up
|
||
go run ./cmd/orbit
|
||
```
|
||
|
||
上方 DSN 为本地占位示例，需替换为实际凭据。部署时使用秘密管理和经过验证的 TLS 配置；迁移账户与运行账户分开授权。运行程序不自动迁移数据库。
|
||
|
||
另一个终端执行 SDK 示例：
|
||
|
||
```sh
|
||
cd sdk/go
|
||
ORBIT_URL=http://127.0.0.1:8080 go run ./examples/health
|
||
```
|
||
|
||
任务接入从 [初始化凭据](docs/api/authentication.md) 开始，再按 [SDK 接入](docs/sdk/README.md) 运行受理/取消示例。[自动 Worker 示例](docs/sdk/worker-runtime.md) 演示处理器注册、并发消费、结果确认与排空；特殊接入也可使用 [底层协议示例](docs/sdk/worker.md)。
|
||
|
||
## 开发与回归
|
||
|
||
```sh
|
||
make fmt
|
||
make test
|
||
make vet
|
||
make build
|
||
make integration
|
||
```
|
||
|
||
`make integration` 要求 Docker、OpenSSL 等标准命令，启动独立的临时 MySQL 容器，使用随机凭据和回环随机端口；完成后删除该测试容器。不会连接已有业务数据库。可通过 `GO`、`DOCKER` 和 `ORBIT_TEST_MYSQL_IMAGE` 指定工具/测试镜像。
|
||
|
||
修改已应用迁移时会触发校验和拒绝；新增结构使用新的前向迁移。初始结构尚未部署生产。
|
||
|
||
## 文档入口
|
||
|
||
- [持续开发与回归计划](docs/08-development-plan.md)
|
||
- [数据模型与约束](docs/07-data-model.md)
|
||
- [HTTP / WebSocket 接口手册](docs/api/README.md)
|
||
- [Go SDK 接入](docs/sdk/README.md)
|
||
- [通用场景示例](docs/examples/README.md)
|
||
- [设计文档总览](docs/README.md)
|
||
|
||
Git 远端：`https://git.yuntuo.hk/k2safe/orbit.git`。当前在本地开发分支推进，SDK 尚未发布版本。
|