Aleph 4.1.7 常用 CLI 命令与工具详解

目标：系统讲清 Aleph 4.1.7 服务端管理 CLI（aleph 命令）的全部子命令与配套工具——初始化、数据摄取、索引重建、用户权限、交叉比对、队列运维，全部子命令清单与选项以 4.1.7 tag 源码（aleph/manage.py）实查为准，标注「实测」的命令均在部署实例上真实执行并逐行照抄回显。

⚠️ 名称澄清：部分旧版资料把 Aleph 管理 CLI 写作 alephcommand，并列有 crawl、createdomains 等子命令。经对 4.1.7 源码与运行实例实测核对：命令入口是 aleph（setup.py aleph = aleph.manage:cli），不存在 createdomains 子命令；文档爬取子命令是 crawldir（crawl 未在 4.1.7 中出现）。旧资料命令请勿直接照抄。

一、环境信息

项	值
操作系统	Ubuntu 22.04（内核 6.8.0-138-generic）
Aleph	4.1.7（官方 Docker 镜像 ghcr.io/alephdata/aleph:4.1.7）
部署形态	官方 Docker Compose 全栈（部署过程见《Aleph Docker Compose 部署指南》）
CLI 入口	aleph（Python 包 aleph 4.1.7，Flask CLI 封装）
实测日期	2026-10-24
管理账号	root@aleph.local（管理员，见部署指南 4.6）
实例内已投数据	官方样例集合 directory:aleph-contrib-testdata（3 个文件：xls/PDF/eml）

二、前置条件

已完成 Aleph 全栈部署（aleph upgrade 已执行、管理员已创建），CLI 依赖业务库与 ES 连接（连接参数见《Aleph 4.1.7 配置参数详解》）；
管理命令统一在部署目录通过 shell 服务入口执行（该服务即官方编排为管理命令准备的执行环境，与线上 worker/api 共享 aleph.env 配置）：

docker compose run --rm shell aleph <子命令> [选项] [参数]

本文所有「实测回显」均省略了启动时的两条固定噪音：Container aleph-417-stack-shell-1 Running/Started 与 pkg_resources 弃用告警（DeprecationWarning: Deprecated call to 'pkg_resources.declare_namespace…'）——该告警无害，是 Python 3.10 环境下的依赖提示。

三、命令查看方式

3.1 总览：aleph --help（实测）

docker compose run --rm shell aleph --help

实测回显（全文）：

Usage: aleph [OPTIONS] COMMAND [ARGS]...

  Server-side command line for aleph.

Options:
  -v, --version         Show the Aleph version.
  -e, --env-file FILE   Load environment variables from this file. python-
                        dotenv must be installed.
  -A, --app IMPORT      The Flask application or factory function to load, in
                        the form 'module:name'. Module can be a dotted import
                        or file path. Name is not required if it is 'app',
                        'application', 'create_app', or 'make_app', and can be
                        'name(args)' to pass arguments.
  --debug / --no-debug  Set debug mode.
  --help                Show this message and exit.

Commands:
  cancel                    Cancel all queued tasks for the dataset.
  cancel-user               Cancel all queued tasks not related to a...
  cleanup-archive
  collections               List all collections.
  crawldir                  Crawl the given directory.
  creategroup               Create a user group.
  createuser                Create a user and show their API key.
  db                        Perform database migrations.
  delete                    Delete a given collection.
  deleterole                Hard-delete a role (user, or group) from the...
  downgrade-database        Downgrade the database.
  dump-entities             Export FtM entities for the given collection.
  dump-profiles             Export profile entityset items for the given...
  evilshit                  EVIL: Delete all data and recreate the database.
  flush                     Flush all the contents for a given collection.
  flushdeleted              Remove soft-deleted database objects.
  flushqueue
  groups                    List all groups.
  hash-plaintext-api-keys   Hash legacy plaintext API keys.
  load-entities             Load FtM entities from the specified iJSON file.
  publish                   Make a collection visible to all users.
  reindex                   Index all the aggregator contents for a...
  reindex-casefiles         Re-index all the casefile collections.
  reindex-full              Re-index all collections.
  reingest                  Process documents and database entities and...
  reingest-casefiles        Re-ingest all the casefile collections.
  renameuser                Rename an already-existing user.
  reset-api-key-expiration  Reset the expiration date of all legacy,...
  resetcache                Clear the redis cache.
  resetindex                Re-create the ES index configuration,...
  retry-exports             Cancel all queued tasks not related to a...
  routes                    Show the routes for the app.
  run                       Run a development server.
  shell                     Run a shell in the app context.
  status                    Get the queue status (pending and finished...
  touch                     Mark a collection as changed.
  update                    Re-index all collections and clear some caches.
  upgrade                   Create or upgrade the search index and database.
  useradd                   Add user to group.
  userdel                   Remove user from group.
  users                     List all users and their groups.
  worker                    Run the queue-based worker service.
  xref                      Cross-reference all entities and documents in...

其中 db、routes、run、shell 四个是 Flask 框架内置命令，其余为 Aleph 业务命令。

3.2 版本与单个子命令帮助（实测）

docker compose run --rm shell aleph -v

实测回显：

Aleph 4.1.7 / Python 3.10.19 / Flask 2.3.3 / Werkzeug 3.1.3

docker compose run --rm shell aleph crawldir --help

实测回显：

Usage: aleph crawldir [OPTIONS] PATH

  Crawl the given directory.

Options:
  -l, --language TEXT    ISO language codes for OCR
  -f, --foreign_id TEXT  Foreign ID of the collection
  --help                 Show this message and exit.

每个子命令都支持 --help（选项定义与源码 manage.py 一致）。

四、核心子命令详解

4.1 初始化与升级（部署/版本变更必用）

upgrade —— 创建/升级数据库与索引

docker compose run --rm shell aleph upgrade

执行 Alembic 数据库迁移 + 创建/对齐全部 ES 索引（60+ 个 aleph-entity-* 索引 + aleph-collection-v1 + aleph-xref-v1）。首次部署、版本升级、异常后修复的标准动作。实测全量回显见部署指南 4.5。

⚠️ 幂等安全：重复执行无副作用（迁移版本已到位时为 no-op）。回滚用 downgrade-database（传 -r <revision>，危险操作，先备份）。

4.2 数据摄取与集合管理

crawldir —— 爬取目录文件入馆（实测）

docker compose run --rm shell aleph crawldir /aleph/contrib/testdata

实测回显（节选）：

2026-10-23 20:07:50 [info     ] Crawling /aleph/contrib/testdata to directory:aleph-contrib-testdata (1)...   [aleph]
2026-10-23 20:07:50 [info     ] Archive: /data                     [servicelayer.archive.file]
2026-10-23 20:07:50 [debug    ] Ingest entity [1.dcf69687…]: aircrafts-iom.xls      [aleph.queues]
2026-10-23 20:07:50 [debug    ] Ingest entity [2.8b3327dd…]: 0adc8f5c….Hearing_Klavdianos_v_Greece_21_09_99.pdf   [aleph.queues]
2026-10-23 20:07:50 [debug    ] Ingest entity [3.e519650d…]: Fwd_Re_Your_Campaign.eml   [aleph.queues]
2026-10-23 20:07:50 [info     ] Complete. Make sure a worker is running :)   [aleph]

要点：

目标目录必须位于执行环境内（官方样例数据目录 /aleph/contrib/testdata 镜像自带；自有数据目录需在编排中挂载进 shell/worker/ingest-file 服务）；
-f directory:my-dataset 显式指定集合 foreign_id（省略则按目录路径自动生成 directory: 前缀 foreign_id）；-l 指定 OCR 语言（如 -l chi_sim+eng，另见配置篇 5.5）；
crawldir 只把文件入队，解析/OCR/索引由 worker 异步完成——收尾提示「Make sure a worker is running」。

collections —— 列出全部集合（实测）

docker compose run --rm shell aleph collections

实测回显：

Foreign ID                    ID  Name
--------------------------  ----  -----------
directory:aleph-contrib…     1  testdata

默认列出普通数据集；--secret 另列隐藏集合、--casefile 列调查案卷。此处拿到的 Foreign ID 是 reindex/reingest/delete/xref 等命令的入参（这些命令收 foreign_id 而非数字 ID，坑见 7.1）。

load-entities / dump-entities —— FtM 实体流导入导出

aleph load-entities <foreign_id> -i entities.ijson     # 导入 iJSON 实体流
aleph dump-entities <foreign_id> -o backup.ijson       # 导出为 iJSON

批量导入外部实体数据（如 OpenSanctions 数据集、自产实体）的正规通道；dump-entities 是实体库备份/迁移工具。可选 --safe/--unsafe（是否跳过已知实体）、--mutable/--immutable、--clean/--unclean（来源：manage.py 选项定义）。

delete / flush / touch —— 集合级操作

aleph delete <foreign_id>          # 删除集合（默认异步；--sync 同步等待；--async 强制异步）
aleph flush <foreign_id>           # 清空集合内容但保留集合框架
aleph touch <foreign_id>           # 标记变更（触发统计/告警重算）

delete/flush 均为破坏性操作，执行前用 collections 核对 Foreign ID。

4.3 索引与重建

reindex —— 单集合重索引（实测，含 ID 坑）

# 错误示范（实测）：传数字 ID 会报错
docker compose run --rm shell aleph reindex 1

实测回显：

Error: Invalid value: No such collection: '1'

正确用法（实测）：

docker compose run --rm shell aleph reindex directory:aleph-contrib-testdata

实测回显：

Starting to re-index
Aggregating model
Indexed 27 entities
Computing statistics
Index: testdata (7 things)

reindex 从实体聚合器重建该集合的索引文档（不重新解析文档），修复「ES 丢了但库里还有」的索引缺失。--flush 先删旧索引再重建。

reindex-full / update / resetindex

aleph reindex-full        # 全库重索引（=对每个集合 reindex，ES 灾后重建主命令）
aleph update              # 全库重索引 + 清缓存（轻量版全量维护，实测见下）
aleph resetindex          # 重建 ES 索引配置（mapping/分析器变更后）

update 实测回显（节选）：

2026-10-23 20:19:07 [info     ] [directory:aleph-contrib-testdata] Computing statistics...   [aleph.logic.collections]
2026-10-23 20:19:07 [info     ] [directory:aleph-contrib-testdata] Index: testdata (7 things)...   [aleph.index.collections]
2026-10-23 20:19:07 [info     ] Updating global statistics cache...   [aleph.logic.collections]

reingest —— 重新解析文档

aleph reingest <foreign_id>            # 重新走 ingest 流水线（--include_ingest 连原始文件一起重跑；--index 仅重建索引）
aleph reingest-casefiles               # 全部案卷重摄取

改了 OCR 语言配置（配置篇 5.5）或 ingest-file 版本后，用 reingest 让存量文档重新解析（任务量大，小步分集合执行）。

4.4 用户与组管理（全组实测）

# 创建管理员（实测）
docker compose run --rm shell aleph createuser -n root -a -p q1w2e3r4 root@aleph.local

实测回显：

User created. ID: 4, API Key: None

（4.1 起新用户默认不发 API Key，需用户在 UI 设置页自行生成，90 天自动过期。）

# 组管理（以下均实测）
docker compose run --rm shell aleph creategroup investigators
# 实测回显: Group investigators created.
docker compose run --rm shell aleph useradd investigators root@aleph.local
# 实测回显: Added user root@aleph.local to group investigators
docker compose run --rm shell aleph groups

groups 实测回显：

Foreign ID             ID  Name
-------------------  ----  -------------
group:investigators     5  investigators

aleph users               # 列出用户与所属组（实测见下）
aleph renameuser <email> <新名>   # 改显示名
aleph userdel <group> <user>      # 移出组
aleph deleterole <foreign_id>     # 硬删除用户/组角色（危险）
aleph reset-api-key-expiration    # 重置存量 API Key 的过期时间
aleph hash-plaintext-api-keys     # 将旧版明文存储的 API Key 散列化（4.1 升级路径用）

users 实测回显：

system:aleph (system service)
root (root@aleph.local)
└── investigators

4.5 交叉比对 xref（实测）

docker compose run --rm shell aleph xref directory:aleph-contrib-testdata

实测回显（节选）：

2026-10-23 20:19:03 [info     ] [directory:aleph-contrib-testdata] xref_collection scroll settings: scroll=5m, scroll_size=1000   [aleph.logic.xref]
2026-10-23 20:19:03 [info     ] [directory:aleph-contrib-testdata] Clearing previous xref state....   [aleph.logic.xref]
2026-10-23 20:19:03 [info     ] [directory:aleph-contrib-testdata] Generating entity-based xref...   [aleph.logic.xref]
2026-10-23 20:19:03 [debug    ] Candidate [Person]: Kevin Kühnert: 0 possible matches   [aleph.logic.xref]
2026-10-23 20:19:03 [info     ] [directory:aleph-contrib-testdata] Generating mention-based xref...   [aleph.logic.xref]
2026-10-23 20:19:03 [info     ] [directory:aleph-contrib-testdata] Xref done, re-indexing to reify mentions...   [aleph.logic.xref]

xref 分两轮：实体级匹配（entity-based）与提及级匹配（mention-based），结果在 UI 的 Cross-reference 面板人工研判、导出 xlsx。注意它依赖模型下载地址（内网需覆盖 ALEPH_FTM_COMPARE_MODEL_URI 等，见配置篇 5.4）。dump-profiles 可导出 xref 产出的 profile 数据。

4.6 队列与后台任务运维

worker —— 启动队列 worker

生产中 worker 由编排常驻（aleph worker 命令）；排障时单独起一个前台 worker 观察：

aleph worker        # 队列消费者（ingest/analyze/index/xref/export 等 op）

status / cancel —— 队列水位与取消（实测）

docker compose run --rm shell aleph status

实测回显（空闲态；高峰期这里是 ingest/analyze/index 各队列的 pending/finished 计数）：

Dataset                     Foreign ID           Pending    Finished

aleph cancel <foreign_id>   # 取消该集合在队列中的任务
aleph cancel-user           # 取消所有用户态任务（保留系统任务）
aleph retry-exports         # 重试失败的导出任务
aleph flushqueue            # 清空队列（含积压任务，配合 reindex-full 做灾后重建）

其他运维件

aleph flushdeleted      # 物理清理软删除对象
aleph resetcache        # 清 Redis 缓存（metadata/统计不刷新时用）
aleph cleanup-archive   # 清理无主归档文件（-p 前缀过滤）
aleph evilshit          # EVIL：清库重建（全实例数据归零，仅测试环境）

五、API 与配套工具

5.1 API 认证（实测发现的格式陷阱）

脚本化操作走 REST API /api/2/*，认证头是两种写法（实测踩点）：

Authorization: Token <jwt>      # 登录会话（POST /api/2/sessions/login 获取）
Authorization: <api_key>        # 裸 API Key 值（4.1 起在 UI 设置页生成，90 天过期）

⚠️ 不要加 Bearer 前缀：实测 Authorization: Bearer <key> 会把整个串当作无效 Key 静默降级为匿名——请求不报错，但只返回公开数据（私有集合搜索结果为空），极易误判为权限配置问题。

搜索示例（实测，登录态）：

GET /api/2/entities?q=Campaign&filter:schemata=Thing
→ {"status": "ok", "total": 1, …}（命中样例邮件实体）

注意查询参数用 filter:schemata=Document 这类 filter: 前缀形式（OpenAPI 规范见 /api/openapi.json）。

5.2 alephclient（独立安装的官方客户端）

与 aleph 服务端 CLI 不同，alephclient 是官方 Python 客户端（PyPI 包，pip install alephclient），用于从外部机器对接已部署实例：alephclient crawl-dir（把本地目录推给远端 Aleph）、alephclient write-entities（实体流导入）、alephclient get-entities（导出）。适合数据源机器与管理机分离的拓扑（来源：官方文档 Open data / API 章节，2026-10-24 核对）。本文聚焦服务端 aleph CLI，客户端细节遇实际需求再展开。

六、常用命令速查表

场景	命令
首次部署/版本升级	`aleph upgrade`
目录数据入馆	`aleph crawldir <目录> -f directory:my-data`
查集合 Foreign ID	`aleph collections`（--secret/--casefile）
修单集合索引	`aleph reindex <foreign_id>`
ES 灾后全库重建	`aleph resetindex && aleph flushqueue && aleph reindex-full`
改 OCR 后重跑存量	`aleph reingest <foreign_id> --include_ingest`
全库例行维护	`aleph update`
建号/建组	`aleph createuser -n <名> -a -p <密码> <邮箱>`；`aleph creategroup <组名>`；`aleph useradd <组> <邮箱>`
跑交叉比对	`aleph xref <foreign_id>`
队列排障	`aleph status` → `aleph cancel <foreign_id>` / `aleph flushqueue`
实体库备份/迁移	`aleph dump-entities <foreign_id> -o out.ijson`；恢复 `aleph load-entities`

七、常见问题（排障实录）

7.1 reindex/reingest 报 No such collection: '1'

这些命令收集合 Foreign ID（如 directory:aleph-contrib-testdata）而非数字 ID。先用 aleph collections 查 Foreign ID（实测报错与修复见 4.3）。

7.2 API 调用拿到空数据但不报错

Bearer 前缀陷阱（5.1 实测）：认证头写 Bearer <key> 被静默降级为匿名。改用裸 Key 或 Token <jwt>。

7.3 crawldir 显示 Complete 但搜索不到

crawldir 只入队不处理。检查 worker：docker compose logs worker --tail 20 看是否消费任务；worker 停滞时 aleph status 看队列水位，重启 worker 服务或 aleph flushqueue 后重投。

7.4 每条命令都打 DeprecationWarning

Python 3.10 下 pkg_resources 弃用告警（pkg_resources.declare_namespace），来自上游依赖，无害可忽略；命令实际执行不受影响。

7.5 误用 aleph run / routes

run（起开发服务器）与 routes（列出路由）是 Flask 内置命令，生产服务由编排管理，不要手工 aleph run 起服务。

八、参考链接

CLI 源码（子命令权威出处）：https://github.com/alephdata/aleph/blob/4.1.7/aleph/manage.py
4.1.7 Release（API Key 变更说明）：https://github.com/alephdata/aleph/releases/tag/4.1.1
官方文档站：https://docs.aleph.occrp.org/
API 规范：https://docs.aleph.occrp.org/developers/api/
系列文档：《Aleph 4.1.7 介绍与选型指南》、《Aleph Docker Compose 部署指南》、《Aleph 4.1.7 配置参数详解》