Hatsu 0.3.5 常用 CLI 命令与工具详解

目标：汇总 Hatsu 0.3.5 的全部操作面——hatsu CLI、just 任务工具链、Admin API、联邦发现端点、数据库检查与日志观测，每条命令的输出都是 2026-11-02 在真实运行实例上的实测记录。先说结论：Hatsu 的运行时 CLI 面极窄（只有 run），运维操作几乎全部走 Admin API 与 curl；建号、封禁、健康检查、数据核对的命令形态本文一次给全。部署上下文见《Hatsu 0.3.5 Docker Compose 部署指南》，配置参数语义见《Hatsu 0.3.5 配置参数详解》。

一、环境信息与命令面总览

组件与版本：Hatsu 0.3.5（hatsu -V 实测回显见第二章），实测实例宿主端口 8144（SQLite 栈）/ 8145（PostgreSQL 栈），token 123e4567-e89b-12d3-a456-426614174000。
命令面构成：

操作面	载体	运行时可用性
启动服务	`hatsu run`	✅ 唯一子命令（官方制品入口即 `run`）
建号/删号/封禁	Admin API（HTTP）	✅ 需 `HATSU_ACCESS_TOKEN`；删号 0.3.5 未实现
健康检查/联邦发现	HTTP 端点	✅ curl 直达
数据库迁移	启动自动（SeaORM）	✅ 无人工命令；`hatsu migrate` 不存在
开发任务（构建/测试/迁移生成）	`just` + Justfile	❌ 仅源码仓库，运行环境无 justfile
数据核对	`psql` / SQLite 客户端	✅ 外部工具

二、hatsu CLI 实测

2.1 可执行文件入口

官方制品把可执行文件放在 /app/hatsu，不在 PATH 里——裸敲 hatsu 找不到命令：

command -v hatsu

hatsu not in PATH

应用目录实测形态：

total 11588
drwxr-xr-x 1 root root     4096 Nov  2 03:30 .
drwxr-xr-x 1 root root     4096 Nov  2 03:24 ..
-rwxr-xr-x 1 root root 11415616 Oct  1 13:04 hatsu
-rw-r--r-- 1 root root   434176 Nov  2 03:30 hatsu.sqlite3

因此一切 CLI 操作使用全路径 /app/hatsu（制品入口脚本本身即调用它）。

2.2 顶层帮助与版本

/app/hatsu --help

Self-hosted & Fully-automated ActivityPub Bridge for Static Sites.

Usage: hatsu [COMMAND]

Commands:
  run   
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

/app/hatsu -V

hatsu 0.3.5

/app/hatsu help 输出与 --help 相同（clap 默认行为）。

2.3 唯一的 run 子命令

/app/hatsu run --help

Usage: hatsu run

Options:
  -h, --help  Print help

注意：run 没有任何命令行参数——全部运行配置走环境变量/.env（见配置篇），不存在 --port、--config 一类旗标。

2.4 不存在的子命令（实测纠偏）

常见猜测的迁移/初始化子命令均不存在：

/app/hatsu migrate

error: unrecognized subcommand 'migrate'

Usage: hatsu [COMMAND]

For more information, try '--help'.
RC=2

数据库迁移由 run 启动时自动执行（11 个迁移版本，见配置篇第五章），Hatsu 0.3.5 没有提供任何人工迁移、初始化、建号 CLI——建号只能走第四章 Admin API。

三、just 任务工具链（开发专用）

官方仓库根目录 Justfile（set dotenv-load）定义的任务族实测摘录：

# create and remove account (method: create/remove) (name: example.com)
account method name:
  #!/bin/sh
  if [ -z ${HATSU_ACCESS_TOKEN+x} ]; then
    echo "env HATSU_ACCESS_TOKEN must be set"
  else
    just _account {{method}} {{name}}
  fi

_account method name:
  curl -X POST "http://localhost:${HATSU_LISTEN_PORT}/api/v0/admin/{{method}}-account?name={{name}}&token=${HATSU_ACCESS_TOKEN}"

# /api/v0/admin/block-url
block-url url:
  curl -X POST "http://localhost:${HATSU_LISTEN_PORT}/api/v0/admin/block-url?url={{url}}&token=${HATSU_ACCESS_TOKEN}"

# /api/v0/admin/unblock-url
unblock-url url:
  curl -X POST "http://localhost:${HATSU_LISTEN_PORT}/api/v0/admin/unblock-url?url={{url}}&token=${HATSU_ACCESS_TOKEN}"

要点：

just 只是 curl 的包装——just account create example.com 等价于第四章的 create-account curl，官方文档也承认「If you are using docker, you need to exec to the container first」，运行时路线直接用 curl 更顺；
其余任务（build/fmt/check/lint/test/up/db_migration/db_schema）全部依赖 cargo/sea-orm-cli，面向源码仓库；其中 db_migration 走 sea-orm-cli migrate up -d crates/db_migration -u $HATSU_DATABASE_URL，是开发者生成/应用迁移的工具，不是运维入口；
运行环境里没有任务文件，实测：

just --list

error: No justfile found

四、Admin API 命令族（运维主战场）

端点族 /api/v0/admin/<action>?<params>&token=<HATSU_ACCESS_TOKEN>，全部 POST。实测速查（宿主 8144，SQLite 栈）：

4.1 create-account 建号

curl -s -w '\nHTTP %{http_code}\n' -X POST 'http://127.0.0.1:8144/api/v0/admin/create-account?name=blog.codingnow.com&token=123e4567-e89b-12d3-a456-426614174000'

{"name":"云风的 BLOG","message":"The account was successfully created: 云风的 BLOG"}
HTTP 201

name 即站点域名；响应里的 name 是自动抓取的 Feed 站点标题。重复建号：

{"error":"The account already exists: 云风的 BLOG","error_id":"01a19a81-fe14-7532-bbb1-56c3eb75832e"}
HTTP 400

4.2 remove-account 删号（0.3.5 未实现）

主账号与普通账号一律 405：

{"name":"github.blog","message":"Remove account API not yet implemented: github.blog"}
HTTP 405

{"name":"blog.codingnow.com","message":"Remove account API not yet implemented: blog.codingnow.com"}
HTTP 405

建错账号目前只能直接操作数据库清理（第六章工具面）。

4.3 block-url / unblock-url 封禁

curl -s -w '\nHTTP %{http_code}\n' -X POST 'http://127.0.0.1:8144/api/v0/admin/block-url?url=https://mastodon.social/&token=123e4567-e89b-12d3-a456-426614174000'

{"url":"https://mastodon.social/","message":"The url was successfully blocked: https://mastodon.social/"}
HTTP 200

{"url":"https://mastodon.social/","message":"The url was successfully unblocked: https://mastodon.social/"}
HTTP 200

语义（官方文档）：url 的 path 为 / 时按实例封禁，精确到 actor 路径时按账号封禁；每收到一条活动做一次 origin 匹配（实例）/精确匹配（账号）。封禁记录持久化在 blocked_url 表（psql 可见，第六章）。

4.4 认证行为

token 传错：401，空响应体：

HTTP 401

实例未配置 HATSU_ACCESS_TOKEN（故障复现栈实测）：无论传什么 token 都 401 空响应——Admin API 整体不可用：

HTTP 401

五、健康检查与联邦端点 curl 速查

以下端点无需 token，实测回显全文见部署篇第六、七章，此处给命令形态：

用途	命令	实测状态码
健康探针	`curl -si http://127.0.0.1:8144/api/v0/generate_204`	`204 No Content`
账号发现	`curl -s 'http://127.0.0.1:8144/.well-known/webfinger?resource=acct:github.blog@hatsu.local'`	200，subject `acct:github.blog@hatsu.local`
NodeInfo 索引	`curl -s http://127.0.0.1:8144/.well-known/nodeinfo`	200，含 2.0/2.1 两个 href
NodeInfo 正文	`curl -s http://127.0.0.1:8144/nodeinfo/2.1.json`	200，`software.version: "0.3.5"`
宿主元数据	`curl -si http://127.0.0.1:8144/.well-known/host-meta`	307 → `/.well-known/host-meta.xml`
Actor	`curl -s -H 'accept: application/activity+json' http://127.0.0.1:8144/users/github.blog`	200，`type: "Service"`
发件箱	`curl -s http://127.0.0.1:8144/users/github.blog/outbox`	200，`OrderedCollection`，`totalItems` 计数
发件箱首页	`curl -s 'http://127.0.0.1:8144/users/github.blog/outbox?page=1'`	200，`Create(Note)` 活动数组
帖子对象	`curl -s http://127.0.0.1:8144/posts/<原文章URL>`	200，Note
notice 兼容	`curl -si http://127.0.0.1:8144/notice/<base64url(ID)>`	308 → 规范帖子 URL

/notice/<base64url> 路径是仿 Pleroma 的兼容面，供 oom-comments 前端反解回复树（/api/v1/statuses/<id>/context 形态），base64url 编码的帖子 ID 实测形如：

ID=aHR0cHM6Ly9naXRodWIuYmxvZy9vcGVuLXNvdXJjZS9nYW1pbmcvZ2FtZS1vZmYtMjAyNi10aGUtdGhlbWUtaXMtc2hpZnQv

六、数据库检查工具面

6.1 PostgreSQL 路线：psql

实测（口令 q1w2e3r4，示例账号 root 管理）：

psql -U hatsu -d hatsu -c '\dt'

             List of relations
 Schema |       Name        | Type  | Owner 
--------+-------------------+-------+-------
 public | activity          | table | hatsu
 public | blocked_url       | table | hatsu
 public | post              | table | hatsu
 public | received_announce | table | hatsu
 public | received_follow   | table | hatsu
 public | received_like     | table | hatsu
 public | seaql_migrations  | table | hatsu
 public | user              | table | hatsu
 public | user_feed_item    | table | hatsu
(9 rows)

常用核对查询（实测回显）：

psql -U hatsu -d hatsu -c 'select name, preferred_username, local from "user";'

      name       | preferred_username | local 
-----------------+--------------------+-------
 The GitHub Blog | github.blog        | t
(1 row)

psql -U hatsu -d hatsu -c 'select count(*) from post;'

 count 
-------
    10
(1 row)

psql -U hatsu -d hatsu -c 'select version from seaql_migrations order by version;'

                  version                   
--------------------------------------------
 m20240131_000001_user
 m20240131_000002_user_feed_item
 m20240131_000003_post
 m20240131_000004_activity
 m20240131_000005_received_follow
 m20240501_000001_received_like
 m20240501_000002_received_announce
 m20240515_000001_user_feed_hatsu_extension
 m20240515_000002_user_feed
 m20240926_000001_blocked_url
 m20241028_000001_user_language
(11 rows)

注意 user 是保留字，查询里要加双引号。

6.2 SQLite 路线：外部客户端

数据库就是 bind 挂载的那个文件（实测 434176 字节）：

-rw-r--r-- 1 root root 434176 Nov  2 12:26 hatsu.sqlite3

表结构与 PostgreSQL 完全同构（同一套 SeaORM 迁移）。应用运行环境不带 sqlite3 命令行工具（实测 command -v sqlite3 无输出），检查 SQLite 库要用宿主或外部的任意 SQLite 客户端打开该文件；405 删号遗留的脏账号、封禁表核对都可在此完成（改库前先停服务）。

七、日志与运行观测

docker compose logs --tail 100 hatsu

日志面构成（实测样本）：

启动里程碑（INFO，hatsu::commands::run）：Hatsu v0.3.5 "Strobe Nights" → loading environment variables → connecting database: <URL> → running database migration → checking primary account: <域名> → setup federation config → starting backend——排障时按这条链定位卡点（部署篇第十章三例各卡在不同环节）；
SQL 流水（INFO，sqlx::query）：逐条语句+耗时，HATSU_LOG=info 时刷屏，压噪声见配置篇 3.5 节；
HTTP 访问（INFO，tower_http::trace）：如 finished processing request, latency: 0 ms, status: 200，出错时 response failed, classification: Status code: 500 Internal Server Error——10.2 节间歇 500 就是靠这两行配对的；
Feed 轮询心跳：整点 5 分钟节拍实测可见（06:20:00、06:25:00 各一轮 SELECT ... FROM "user" WHERE "user"."local" = ?），新文章即在此轮被广播。

资源占用用 docker stats 一次性核对（实测 8 MiB 常驻，见部署篇第九章）。

八、小结与速查

想做的事	0.3.5 的正确姿势
启动/重启服务	`hatsu run`（入口自动带）/ `docker compose restart`
建新账号	Admin API `create-account`（201）
删账号	❌ API 未实现（405），手工清库
封/解封实例或账号	Admin API `block-url` / `unblock-url`（200）
跑迁移	无需操作，启动自动；人工迁移仅开发态 `sea-orm-cli`
健康检查	`GET /api/v0/generate_204`（204）
核对联邦身份	webfinger / nodeinfo / actor / outbox curl
查数据	psql（PG）或外部 SQLite 客户端（文件库）
降噪日志	`HATSU_LOG=info,sqlx::query=warn`（进程环境注入）

Hatsu 0.3.5 的 CLI 面「薄」到只有一个 run，这是单进程桥接器的设计取舍：状态全在库里、操作全在 HTTP 上。配合配置篇（《Hatsu 0.3.5 配置参数详解》）与部署篇（《Hatsu 0.3.5 Docker Compose 部署指南》）构成本专栏的完整运维闭环。