# 命令行控制台 `chongming-task` 是**另一个进程**：它看不到任务进程的内存，只能通过共享存储查询与 控制。这正是持久层存在的理由——没有它，`ps` 什么也看不到。 ```bash # 一个终端里跑任务（前台执行到结束） chongming-task --db /var/lib/tasks.db run --tasks myapp.tasks sync --arg tenant=A # 另一个终端里看和管 chongming-task --db /var/lib/tasks.db ps chongming-task --db /var/lib/tasks.db status demo-1 chongming-task --db /var/lib/tasks.db stop demo-1 --reason "发布窗口" ``` --- ## 1. 命令总览 | 命令 | 作用 | |---|---| | `tasks --tasks MODULE` | 列出某个任务模块里注册的定义（名字、标签、描述） | | `run TASK --tasks MODULE [--executor thread\|process]` | 提交并**前台执行**一个任务，直到落终态 | | `ps [--all] [--status S] [--bucket N] [--pipeline RUN_ID] [--mine] [--limit N]` | 列出任务。默认只显示**未落终态**的 | | `status TASK_ID` | 单个任务的详情 + 迁移历史 | | `history TASK_ID` | 只列迁移历史（可审计轨迹） | | `stats` | 各状态计数 | | `buckets [--num-buckets N]` | 每个桶的任务数 | | `reconcile [--dry-run] [--stale-after S] [--reason R]` | **重启恢复**：清理上次进程留下的僵尸任务 | | `stop TASK_ID [--reason R]` | 请求停止 | | `pause TASK_ID [--timeout S]` | 请求暂停 | | `resume TASK_ID` | 恢复被暂停的任务 | 全局选项： | 选项 | 说明 | |---|---| | `--db PATH_OR_DSN` | 任务存储：SQLite 文件路径，或 `postgresql://` 连接串（跨机部署；需要 `pip install "chongming-task[postgres]"`）。未给出时读环境变量 `CHONGMING_TASK_DB` | | `--num-buckets N` | 集群的桶数。**必须与部署一致**——它决定 `--owned-buckets` 的合法性与 `buckets` 视图的行数；不给出按默认值 64 | | `--owned-buckets SPEC` | 本节点负责的桶，如 `0-15,20,30`。给出后 `reconcile` 只清理这些桶、`ps --mine` 只看这些桶 | | `--json` | 以 JSON 输出，便于脚本消费 | | `--owner NAME` | 本客户端的标识，会写进它下发的指令里，便于事后追溯是谁按的停止 | ### 退出码 | 码 | 含义 | |---|---| | `0` | 命令成功 | | `1` | 命令本身失败（参数错、任务不存在、存储打不开、目录不存在……） | | `3` | 命令成功，但它查询/执行的**任务没有成功** | `3` 是给脚本判分支用的： ```bash if ! chongming-task --db tasks.db run --tasks myapp.tasks load --arg day=2026-10-02; then echo "任务没成功，别继续往下走了" >&2 exit 1 fi ``` > 注意 `1` 与 `3` 的区别：`1` 是"我连命令都没跑成"，`3` 是"命令跑成了，但任务本身 > 没成功"。混在一起会让脚本无法区分"运维脚本写错了"和"数据质量有问题"。 --- ## 2. 任务定义从哪里来 CLI **只传任务名，绝不接受代码**——一个能启动任意可调用对象的命令行入口等于任意 代码执行。所以必须先有一个模块把定义登记进来： ```python # myapp/tasks.py def sync_tenant(ctx, tenant: str, batches: int = 120) -> str: """同步一个租户的数据。""" for index in range(batches): ctx.checkpoint() ... return f"{tenant} 同步完成" def register(controller) -> None: """约定：CLI 导入模块后会调用它。""" controller.register("sync", sync_tenant, tags={"io"}) ``` 然后 `--tasks myapp.tasks`。模块必须在 `PYTHONPATH` 上（或是一个已安装的包）。 仓库里的 `examples/tasks_demo.py` 就是一个可直接用的例子： ```bash PYTHONPATH=examples chongming-task tasks --tasks tasks_demo ``` ``` NAME TAGS MAX_ATTEMPTS DESCRIPTION ------------------------------------------------------------ add cpu 1 两数相加。 flaky - 1 前几次故意失败，用来演示重试。 sync io 1 同步一个租户的数据。 ``` 模块没有 `register` 时会给一句明确的话，而不是 `AttributeError`： ``` 错误：任务模块 'json' 必须定义 register(controller) 函数。 ``` --- ## 3. 完整走查 以下全部是**真实运行输出**（`examples/tasks_demo.py`，先在一个终端启动，再从另一个 终端查询与控制）。 ### 3.1 启动一个长任务（前台） ```bash chongming-task --db .cli-demo/tasks.db run --tasks tasks_demo sync \ --arg tenant=租户A --arg batches=20000 --bucket-key tenant-A \ --task-id demo-1 --label A-同步 ``` `run` 是**前台**的：它自己就是 worker，执行到任务落终态才退出。要后台跑就交给 `nohup`、`systemd` 或你已有的进程管理器——CLI 不假装自己是守护进程管理器。 ### 3.2 从另一个进程查询 ```bash chongming-task --db .cli-demo/tasks.db ps ``` ``` TASK_ID NAME BUCKET STATUS ATTEMPT ELAPSED PROGRESS FAILURE ------- ------ ------ ------- ------- ------- -------- ------- demo-1 A-同步 7 running 1/1 7.4s - - ``` ```bash chongming-task --db .cli-demo/tasks.db status demo-1 ``` ``` task_id : demo-1 name : A-同步 status : running bucket : 7 tags : io bucket_key : tenant-A attempt : 1/1 status_version : 3 executor : thread created_at : 2026-10-02T14:01:23+00:00 started_at : 2026-10-02T14:01:23+00:00 ended_at : - last_heartbeat_at : 2026-10-02T14:01:31+00:00 elapsed : 7.8s progress : - failure : - retryable : - overridden : False 迁移历史： VER FROM TO AT TRIGGER ACTOR REASON --- -------- --------- ------------------------- ---------------------------------- ------ ------ 1 pending queued 2026-10-02T14:01:23+00:00 orchestrator:dependencies_resolved system - 2 queued starting 2026-10-02T14:01:23+00:00 scheduler:dispatch system - 3 starting running 2026-10-02T14:01:23+00:00 executor:launched system - ``` **`last_heartbeat_at` 只有在这里才有意义。** 它由任务自己的 `ctx.checkpoint()` 驱动， 所以一个"卡住但没报错"的任务会显示心跳停滞——这是唯一能发现死锁的信号。 `ps` 的 `PROGRESS` 列来自任务里的 `ctx.progress(...)`。它走**高频旁路**（不参与乐观 并发），由持有任务的进程定期回写，因此可能有最多一个轮询周期的延迟： ``` TASK_ID NAME STATUS PROGRESS ---------------------- ------------------- --------- -------- 2b4e5e326776:extract daily-etl/extract succeeded 6/6 2b4e5e326776:load daily-etl/load succeeded 4/4 ``` `stats` 与 `buckets`： ``` $ chongming-task --db .cli-demo/tasks.db stats running 1 -------------------- total 1 unfinished 1 $ chongming-task --db .cli-demo/tasks.db buckets --num-buckets 10 BUCKET TASKS -------------- 0 0 ... 7 1 ... ``` ### 3.3 暂停与恢复 ```bash chongming-task --db .cli-demo/tasks.db --owner ops@console pause demo-1 ``` ``` 已请求暂停 demo-1（用 status 观察是否真的挂起） 暂停**未确认**。若任务由别的进程持有，这是正常的——跨进程没有回执通道，请用 status 观察结果。 ``` 第一行在 stdout，第二行在 stderr，**退出码仍是 0**。跨进程没有回执通道，所以 `pause` 只能如实说"未确认"——这不是失败，而是它做不到的事就别假装做到。 紧接着 `ps` 能看到它确实停了： ``` TASK_ID NAME BUCKET STATUS ATTEMPT ELAPSED PROGRESS FAILURE ------- ------ ------ ------ ------- ------- -------- ------- demo-1 A-同步 7 paused 1/1 18.4s - - ``` `resume` 之后回到 `running`。 ### 3.4 停止，并留下原因 ```bash chongming-task --db .cli-demo/tasks.db --owner ops@console stop demo-1 --reason "发布窗口" chongming-task --db .cli-demo/tasks.db ps --all ``` ``` TASK_ID NAME BUCKET STATUS ATTEMPT ELAPSED PROGRESS FAILURE ------- ------ ------ ------- ------- ------- -------- --------- demo-1 A-同步 7 stopped 1/1 20.9s - cancelled ``` 原因会完整落进审计轨迹，并且**区分了是谁按的**： ``` $ chongming-task --db .cli-demo/tasks.db history demo-1 VER FROM TO AT TRIGGER ACTOR REASON --- -------- -------- ------------------------- ---------------------------------- ------ ------ 1 pending queued 2026-10-02T14:01:23+00:00 orchestrator:dependencies_resolved system - 2 queued starting 2026-10-02T14:01:23+00:00 scheduler:dispatch system - 3 starting running 2026-10-02T14:01:23+00:00 executor:launched system - 4 running pausing 2026-10-02T14:01:40+00:00 user:pause user - 5 pausing paused 2026-10-02T14:01:40+00:00 runtime:pause_reached system - 6 paused running 2026-10-02T14:01:42+00:00 user:resume user - 7 running stopping 2026-10-02T14:01:44+00:00 user:stop user 发布窗口 8 stopping stopped 2026-10-02T14:01:44+00:00 runtime:stop_confirmed system 发布窗口 ``` 第 4–6 行是暂停往返，第 7–8 行是停止。**`REASON` 只在人为动作上出现**——机器自己的 迁移没有原因要记。 ### 3.5 `--json`：给脚本用 ```bash chongming-task --db .cli-demo/tasks.db --json ps --all ``` ```json [{"attempt": 1, "bucket": 7, "bucket_key": "tenant-A", "created_at": "2026-10-02T14:01:23.570947+00:00", "ended_at": "2026-10-02T14:01:44.485082+00:00", "executor": "thread", "failure": "{...}", "last_heartbeat_at": "2026-10-02T14:01:44.430100+00:00", "max_attempts": 1, "name": "A-同步", "outcome": null, "overridden": 0, "status": "stopped", "status_version": 8, "tags": "[\"io\"]", "task_id": "demo-1"}] ``` JSON 与**存储行同构**（全部是原语），因此脚本消费它不需要了解 `datetime` / 枚举的 序列化规则。三点约定： * 时间是 ISO 字符串（UTC）； * 枚举是 `.value` 字符串； * 嵌套结构（`failure` / `outcome` / `tags`）是 JSON **字符串**而不是对象——保持与 存储行一致，代价是脚本里要多一次 `json.loads`。 错误走 stderr，stdout 保持干净，所以 `--json` 的输出可以直接管道给 `jq`。 ### 3.6 按管道查看 管道里的每个任务都带 `pipeline_run_id`（形如 `ead248368f4a:load` 的 task_id），因此 可以整条一起看： ```bash chongming-task --db tasks.db ps --all --pipeline ead248368f4a ``` 过滤**下推到存储层**（SQLite 侧有 `idx_tasks_pipeline_run` 索引），不是取回全部再筛。 `--pipeline` 也可以与 `--status` 组合： ```bash # 这条管道里有哪些节点没成功 chongming-task --db tasks.db ps --status failed --pipeline ead248368f4a ``` --- ## 4. 多节点：`--owned-buckets` 与 `--num-buckets` 多个节点各跑各的任务时，靠桶区分"哪一份是我的"。两个选项都必须与部署一致： ```bash # 只看"我这一份" chongming-task --db tasks.db --num-buckets 64 --owned-buckets 0-15 ps --all --mine # 每个桶多少任务；星号标出本节点负责的桶 chongming-task --db tasks.db --num-buckets 64 --owned-buckets 0-15 buckets ``` ``` BUCKET TASKS ---------------- * 0 3 * 1 0 2 0 ``` `reconcile` 会**限定在自己负责的桶内**： ```bash chongming-task --db tasks.db --owned-buckets 0-15 reconcile --dry-run ``` **`run` 同样受归属约束**：限定了 `--owned-buckets` 时，`--bucket-key` 是必需的——没有归属 桶的任务不会有任何节点认领它，所以 CLI 在提交时就报错，而不是留下一个永远排队的任务： ``` $ chongming-task --db tasks.db --num-buckets 64 --owned-buckets 0-15 run \ --tasks myapp.tasks worker --task-id orders-worker 错误：本节点只负责桶 [0, 1, ..., 15]，因此提交任务 'orders-worker' 时必须给出 bucket_key ——否则它没有归属桶，不会有任何节点认领它。 ``` 这很重要：统一存储里有别的节点的任务，去动它既越界（那是它的责任）也没有意义（它的租约 由它自己续）。 **桶归属的校验在做任何事之前完成**，包括 `ps` / `stats` / `buckets` 这些不构造 `Controller`、直接查存储的命令。否则越界的桶号会被静默接受——筛选条件匹配不到任何东西， 看起来就像"这个桶没有任务"： ``` $ chongming-task --db tasks.db --owned-buckets 0-999 ps 错误：桶号越界：64；桶数是 64（合法范围 0..63）。若部署的桶数不是 64，请用 --num-buckets 指明。 ``` ### 4.1 `run --executor process`：能被真的杀掉的执行方式 默认的线程执行器在"任务不响应停止"时只能放弃等待（记 `lost`，结果未知）。需要**停得住** 的保证时，让任务跑在独立子进程里： ```bash # 前台跑一个可能不配合的任务 chongming-task --db tasks.db run --tasks tasks_demo sync --arg tenant=acme --executor process --graceful-stop 5 # 另一个终端：优雅窗口用尽后会 terminate() → kill()，任务被真的停掉 chongming-task --db tasks.db stop --reason "跑太久" ``` 代价写在这里，省得踩了才知道（与库的行为完全一致，见[用户指南 §7.4](user-guide.md#74-进程执行器硬性停止--绕开-gil--崩溃隔离)）： - **参数与返回值必须可 pickle**——`lambda`、闭包、局部函数都不行；违反时提交那一刻就报错； - **任务函数必须在可导入的模块里**（`--tasks` 指定的那个模块正好满足），且该模块的顶层 不能有副作用； - 停止与暂停有约 20ms 的轮询延迟（信号要过进程边界）。 `run` 输出里的 `pid` 就是那个子进程的进程号，`ps` 能直接对上号。 ### 4.2 跨机部署：`--db` 换成连接串 SQLite 文件不能跨机共享。多台机器共用一套存储时，给 `--db` 一个 Postgres 连接串即可： ```bash pip install "chongming-task[postgres]" chongming-task --db 'postgresql://user:pw@db.internal:5432/chongming' \ --num-buckets 64 --owned-buckets 0-15 ps --all --mine ``` **除连接串本身，其余一切都一样**：`--json`、退出码、`--owned-buckets` 校验、`reconcile` 的语义都不变。三张表（`tasks` / `transitions` / `commands`）在首次连接时自动创建，不需要 手工迁移；当前角色没有建表权限时，它检测到表已存在就直接使用——**只读运维账号因此也能连**。 没装可选依赖时给的是安装命令，而不是一个 `ModuleNotFoundError`： ``` $ chongming-task --db postgresql://… ps 错误：--db 给的是 Postgres 连接串，但可选依赖未安装：PostgresTaskStore 需要可选依赖 psycopg 与 psycopg-pool。安装： pip install "chongming-task[postgres]" 或：pip install "psycopg[binary]" psycopg-pool ``` 连不上时同样只说该说的——DSN 里的**密码不会出现在任何错误信息里**： ``` $ chongming-task --db 'postgresql://someuser:s3cret@nope.invalid:5432/x' ps 错误：无法连接 Postgres（someuser@nope.invalid:5432/x）：failed to resolve host 'nope.invalid': [Errno 11001] getaddrinfo failed ``` --- ## 5. 重启恢复：`reconcile` 进程意外退出后，存储里会留下一批永远停在 `running` 的任务。**新进程启动时先跑一次 `reconcile`**，否则看板会永远显示一个假的"运行中"。 真实输出。先看崩溃后的现场： ``` $ chongming-task --db crash.db ps TASK_ID NAME BUCKET STATUS ATTEMPT ELAPSED PROGRESS FAILURE ----------- ------------ ------ ------- ------- ------- -------- ------- job-queued 等待中的任务 - queued 0/1 - - - job-crashed 夜间抽取 - running 1/1 600.4s - - ``` `job-crashed` 已经"运行"了 600 秒——它的进程其实十分钟前就没了。 **先预演**（这类操作会改状态，看一眼是值得的）： ```bash chongming-task --db crash.db reconcile --dry-run ``` ``` OUTCOME TASK_ID WAS DETAIL ----------- ----------- ------- ----------------- adoptable job-queued queued 没有执行载体，等待重新提交 marked-lost job-crashed running 监督者已失联（进程重启后未再续租） 预演：有 1 个任务**会被**标记为 lost，1 个等待重新提交。未写入任何状态。 注意：本命令不会、也无法重新执行任务——存储里记的是状态，不是参数。 ``` 确认无误后真正执行： ```bash chongming-task --db crash.db reconcile --reason "worker-old 崩溃" ``` ``` 已把 1 个僵尸任务标记为 lost，1 个任务无人接手（状态未改动，需要重新提交）。 ``` 之后 `ps --all` 里 `job-crashed` 是 `lost`，而 `job-queued` **仍然是 `queued`**—— 它没占执行资源，只是没人接手，把它的排队事实改掉才是错的。原因也进了审计轨迹： ``` $ chongming-task --db crash.db history job-crashed VER FROM TO AT TRIGGER ACTOR REASON --- ------- ---- ------------------------- ---------------------- ------ ------------- 4 running lost 2026-10-02T14:10:47+00:00 runtime:heartbeat_lost system worker-old 崩溃 ``` ### 两件必须清楚的事 1. **它不会、也无法重新执行任务。** 存储里记的是状态，不是配方：任务的函数与参数从未 落库。所以"重跑"只能靠你重新 `run`，而那需要你自己知道参数。 2. **判据是租约，不是心跳。** 一个长时间不调 `checkpoint()` 的健康任务心跳也会停滞； 若拿心跳判断进程存活，它会被误判丢失并**杀掉**。所以心跳与租约是两个独立字段。 `--stale-after` 只影响"从未续过租的任务"的宽限期（默认取租约时长的两倍），用来避开 "刚提交、工作线程还没轮到第一次续租"这个窗口。 --- ## 6. 错误路径 ``` $ chongming-task ps 错误：未指定任务存储。请用 --db PATH，或设置环境变量 CHONGMING_TASK_DB。 CLI 是另一个进程，没有共享存储就看不到任何任务。 $ chongming-task --db .cli-demo/tasks.db stop typo-task-id 错误：没有找到任务 typo-task-id；无法停止。 $ chongming-task --db /nope/tasks.db ps 错误：数据库所在目录不存在：/nope。请先创建它，或改用别的路径。 ``` 最后一条是刻意加的：SQLite 原本只会报 `unable to open database file`，完全看不出是 目录不存在——这是最容易浪费时间的错误之一。 --- ## 7. 桌面上的注意事项 * **`run` 是前台进程。** 它退出时任务就没人管了。要长期跑请交给进程管理器。 * **`pause` 跨进程返回"未确认"。** 想看结果请 `status`；`stop` 则是"请求已受理"。 * **`stop` 一个不存在的任务会失败并留下零条指令。** 拼错的 id 不会制造孤儿指令。 * **`ps` 默认不含已结束的任务。** 想看历史加 `--all`，或按状态过滤 `--status failed`。 * **`--db` 必须显式给出或设环境变量。** 不会静默在当前目录建一个库——那类"我的任务 去哪了"的问题很难查。 --- ## 8. 与库的关系 CLI 是 `Controller` 之上的一层**薄适配**：它做的全部事情就是解析参数、调 `Controller` / `TaskStore`、渲染输出。所以： * 库能做的，CLI 不一定都暴露（比如 `wait_all`、`close_store`、`prune`）——直接在代码里用 [Controller](user-guide.md#8-管理一批任务controller) 更灵活； * CLI 不引入任何库没有的概念，也不绕过任何不变量（比如它不会直接改状态）。 替换持久层的步骤见 [持久层实现指南](store-guide.md)——CLI 会自动用上你的实现，因为它 只依赖 `TaskStore` 契约。