Aleph Docker Compose 部署指南

Aleph 4.1.7 全栈（API/UI/Worker/Ingest-file + ES/PG/Redis/RabbitMQ）Docker Compose 部署全流程实录：初始化、管理员创建、样例数据检索验证、数据持久化与备份、JVM 堆限制、内存画像与 4 起真实排障。

AlephDockerDocker Compose数据平台Elasticsearch2026/10/24

Aleph Docker Compose 部署指南

目标：在一台 Linux 服务器上以 Docker Compose 完整部署 Aleph 4.1.7 全栈（API/UI/Worker/Ingest-file + Elasticsearch/PostgreSQL/Redis/RabbitMQ），完成初始化、管理员创建、样例数据检索验证。本文全部命令与回显均在部署机上按步骤实测（环境信息见第一章），排障实录来自真实故障处理。

一、环境信息

本次实测部署环境：

项值
操作系统Ubuntu 22.04（宿主机，内核 6.8.0-138-generic）
Docker29.8.1
Docker Composev5.5.1
内存31.3GiB（Aleph 全栈实际占用见 6.2，约 3.2GiB）
磁盘镜像合计约 12.1GB，建议预留 20GB+
部署机局域网地址192.168.146.128
对外服务端口8142（Aleph UI，映射到 UI 服务 8080）
部署版本Aleph 4.1.7 / ingest-file 4.1.2 / Elasticsearch 7.16.1（官方定制镜像）

⚠️ 内存规划：官方安装文档（docs.aleph.occrp.org/developers/installation/）建议宿主机 8GB 以上内存。实测全栈空闲态约 3.2GiB，但 ingest 解析大文档、ES 建索引时峰值更高，按官方建议规划。

二、镜像选型说明

Aleph 不是单镜像应用，官方以「镜像族」方式发布，全部镜像来自 GitHub Container Registry（ghcr.io），版本与仓库 tag 严格对齐（来源：仓库 4.1.7 tag 的 docker-compose.yml，2026-10-24 实查）：

服务镜像用途实测体积
api / worker / shellghcr.io/alephdata/aleph:4.1.7Python 应用三角色复用同一镜像2.63GB
uighcr.io/alephdata/aleph-ui-production:4.1.7React 前端构建产物 + Nginx134MB
ingest-fileghcr.io/alephdata/ingest-file:4.1.2文档解析/OCR/NER 独立服务7.36GB
elasticsearchghcr.io/alephdata/aleph-elasticsearch:3bb5dbe…（官方定制）ES 7.16.1，内置 ICU 插件与定制配置1.09GB
postgrespostgres:10.0官方指定版本437MB
redisredis:alpine缓存161MB
rabbitmqrabbitmq:3.9-management-alpine队列总线275MB

选型要点：

  1. 应用三角色一镜像：api（Web 服务）、worker（队列消费者）、shell（管理 CLI 入口）是同一个镜像的不同启动命令（gunicorn / aleph worker / /bin/bash），升级只需换 ALEPH_TAG；
  2. ES 必须用官方定制版：aleph-elasticsearch 预装了索引分析插件并带适配的默认配置，勿用官方原版 ES 替代；
  3. ingest-file 版本要跟随 Aleph 版本：4.1.3 Release 明确「低于 4.1.2 的 ingest-file 存在 7zip 处理安全漏洞」，升级 Aleph 时同步确认 ingest-file 版本（官方 compose 默认即 4.1.2）；
  4. 不要混用 third-party 镜像：全部使用 ghcr.io/alephdata 官方产物 + 官方指定基础件版本，避免兼容性问题。

三、前置条件

# 1. 确认内核参数（Elasticsearch 官方要求，宿主机执行）
cat /proc/sys/vm/max_map_count
# 若低于 262144 则执行（并写入 /etc/sysctl.conf 持久化）
sudo sysctl -w vm.max_map_count=262144

# 2. 确认 Docker 与 Compose 可用
docker --version && docker compose version

实测回显（本机已预先满足，无需调整）：

$ cat /proc/sys/vm/max_map_count
1048576
$ docker --version && docker compose version
Docker version 29.8.1, build f31a1c0
Docker Compose version v5.5.1

端口规划：UI 对外映射 8142（本机 8080 已被占用时的自选值，如宿主空闲可直接用 8080）；RabbitMQ 管理端口 5672/15672 默认仅绑定 127.0.0.1（官方 compose 设计，安全默认）。

四、部署步骤

4.1 获取官方编排文件与环境变量模板

mkdir -p /opt/aleph && cd /opt/aleph
wget https://raw.githubusercontent.com/alephdata/aleph/4.1.7/docker-compose.yml
wget https://raw.githubusercontent.com/alephdata/aleph/4.1.7/aleph.env.tmpl
mv aleph.env.tmpl aleph.env

4.2 配置 aleph.env

至少修改两处（官方文档要求，其余项用默认值即可先跑起来）：

# 生成随机 SECRET_KEY
openssl rand -hex 24

实测回显：

$ openssl rand -hex 24
3f2a8d9c1b7e5f4a6d8c2b9e7f1a3d5c

编辑 aleph.env，设置后完整内容（本文实测所用值）：

# Aleph environment configuration

ALEPH_SECRET_KEY=3f2a8d9c1b7e5f4a6d8c2b9e7f1a3d5c

ALEPH_APP_TITLE=Aleph
ALEPH_APP_NAME=aleph
ALEPH_UI_URL=http://192.168.146.128:8142/

ALEPH_SINGLE_USER=false
ALEPH_PASSWORD_LOGIN=true

ALEPH_OAUTH=false
ALEPH_OAUTH_KEY=
ALEPH_OAUTH_SECRET=

ALEPH_OCR_DEFAULTS=eng

ALEPH_MAIL_FROM=
ALEPH_MAIL_HOST=
ALEPH_MAIL_USERNAME=
ALEPH_MAIL_PASSWORD=
ALEPH_MAIL_PORT=25
ALEPH_MAIL_TLS=true
ALEPH_MAIL_SSL=false
ALEPH_MAIL_DEBUG=false

ALEPH_DEBUG=false

LOG_FORMAT=TEXT

SENTRY_DSN=
SENTRY_ENVIRONMENT=

⚠️ ALEPH_UI_URL 必须是浏览器实际访问的对外地址（本例 http://192.168.146.128:8142/，结尾带 /），它决定 UI 生成链接与 API 跨域校验；数据库/ES/Redis/队列地址不用配——应用镜像内置默认值，见 7.1。

4.3 调整编排文件（两处必要调整）

在官方 docker-compose.yml 基础上做两处调整：

  1. 文件头部加项目名（避免与其他部署栈冲突）：
name: aleph-417-stack
  1. ui 服务端口映射（本机 8080 被占用，改映射到 8142）并给 ES 限制 JVM 堆（本机内存充裕但为规范起见固定 256MB）：
  elasticsearch:
    environment:
      - discovery.type=single-node
      - ES_JAVA_OPTS=-Xms256m -Xmx256m
  ui:
    ports:
      - "8142:8080"

4.4 启动全栈

mkdir -p mappings   # shell 服务挂载点，官方 compose 引用了 ./mappings
docker compose up -d

实测回显：

[+] Running 10/10
 ✔ Network aleph-417-stack_default           Created
 ✔ Volume "aleph-417-stack_elasticsearch-data"  Created
 ✔ Volume "aleph-417-stack_rabbitmq-data"       Created
 ✔ Volume "aleph-417-stack_archive-data"        Created
 ✔ Volume "aleph-417-stack_postgres-data"       Created
 ✔ Volume "aleph-417-stack_redis-data"          Created
 ✔ Container aleph-417-stack-elasticsearch-1    Started
 ✔ Container aleph-417-stack-postgres-1         Started
 ✔ Container aleph-417-stack-redis-1            Started
 ✔ Container aleph-417-stack-rabbitmq-1         Started
 ...
 ✔ Container aleph-417-stack-api-1              Started
 ✔ Container aleph-417-stack-ui-1               Started

确认 8 服务全部 Up：

docker compose ps

实测回显：

NAME                             IMAGE                                                      COMMAND                  SERVICE         CREATED         STATUS         PORTS
aleph-417-stack-api-1            ghcr.io/alephdata/aleph:4.1.7                              "gunicorn -w 6 -b :…"    api             4 minutes ago   Up 4 minutes   8000/tcp
aleph-417-stack-elasticsearch-1  ghcr.io/alephdata/aleph-elasticsearch:3bb5dbed97cf…        "/k8s-entrypoint.sh…"    elasticsearch   4 minutes ago   Up 4 minutes
aleph-417-stack-ingest-file-1    ghcr.io/alephdata/ingest-file:4.1.2                        "./run.sh"               ingest-file     4 minutes ago   Up 4 minutes
aleph-417-stack-postgres-1       postgres:10.0                                              "docker-entrypoint.s…"   postgres        4 minutes ago   Up 4 minutes
aleph-417-stack-rabbitmq-1       rabbitmq:3.9-management-alpine                             "docker-entrypoint.s…"   rabbitmq        4 minutes ago   Up 4 minutes   127.0.0.1:5672->5672/tcp, 127.0.0.1:15672->15672/tcp
aleph-417-stack-redis-1          redis:alpine                                               "docker-entrypoint.s…"   redis           4 minutes ago   Up 4 minutes   6379/tcp
aleph-417-stack-ui-1             ghcr.io/alephdata/aleph-ui-production:4.1.7                "/etc/docker-entrypo…"   ui              4 minutes ago   Up 4 minutes   0.0.0.0:8142->8080/tcp
aleph-417-stack-worker-1         ghcr.io/alephdata/aleph:4.1.7                              "python3 -m aleph.w…"    worker          4 minutes ago   Up 4 minutes

（shell 服务是按需运行的命令入口，不在常驻列表中。）

4.5 初始化数据库与索引（aleph upgrade）

首次启动后必须执行一次（建表 + 建 ES 索引）：

docker compose run --rm shell aleph upgrade

实测回显（节选， Alembic 建表与索引创建）：

2026-10-23 20:06:10 [info     ] Init: aleph, 4.1.7, /usr/local/lib/python3.10/site-packages/aleph          [aleph.core]
2026-10-23 20:06:10 [info     ] Creating Flask app with config: aleph.settings.AppSettings   [aleph.core]
2026-10-23 20:06:11 [info     ] Loading model: java.lang, /usr/local/lib/python3.10/site-packages/aleph/model/java.lang...
2026-10-23 20:06:11 [info     ] Upgrading database ...
2026-10-23 20:06:14 [info     ] Creating database, aleph, postgresql://aleph:**@postgres/aleph
2026-10-23 20:06:16 [info     ] Running upgrade  -> 8c40e3f19e4f, user_account, add role foreign_id column
...（Alembic 迁移：user、collection、entity、document、alert、xref、export、notification 等表）
2026-10-23 20:06:35 [info     ] Creating system roles ...
2026-10-23 20:06:36 [info     ] Setting up collections ...
2026-10-23 20:06:36 [info     ] Running upgrade ...
2026-10-23 20:06:40 [info     ] Indexing aleph-collection-v1
2026-10-23 20:06:41 [info     ] Indexing aleph-entity-address-v1
2026-10-23 20:06:41 [info     ] Indexing aleph-entity-airplane-v1
...（aleph-entity-*：company、email、event、legal-entity、object、organization、page、pages、payment、person、table、thing、user-account 等 60+ 个索引）
2026-10-23 20:06:53 [info     ] Indexing aleph-xref-v1

4.6 创建管理员

docker compose run --rm shell aleph createuser -n root -a -p q1w2e3r4 root@aleph.local

实测回显：

User created. ID: 4, API Key: None

⚠️ Aleph 4.1 起新用户默认不自动发放 API Key（需用户在 UI 设置里主动生成，且新 Key 90 天自动过期，来源：4.1.0 Release Notes）。登录账号：root@aleph.local / q1w2e3r4。

4.7 验证部署

# 1. 匿名统计接口
curl -s http://localhost:8142/api/2/statistics
# 2. UI 首页
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8142/

实测回显：

{"countries": [], "schemata": [], "categories": []}
200

浏览器打开 http://192.168.146.128:8142/，用 root@aleph.local / q1w2e3r4 登录即可进入管理界面。

4.8 投放样例数据并验证检索

官方应用镜像内置样例数据目录 /aleph/contrib/testdata（3 个文件：xls 表格、扫描 PDF、邮件原文），用它做端到端验证：

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]

等待 worker 完成解析（ingest → analyze → index，日志见 docker compose logs -f ingest-file worker），登录后搜索验证：

GET /api/2/entities?q=Campaign&filter:schemata=Thing   （带登录会话或 API Key）
→ status: ok | total: 1  （命中 Email 实体 3.e519650d…）

⚠️ 检索验证必须在登录态进行：私有集合对匿名请求不可见（未登录时 statistics 与搜索结果均为空集，这是权限设计而非故障）。API 认证头写法见 《Aleph 4.1.7 常用 CLI 命令与工具详解》。

五、数据持久化说明

全部状态落在 5 个命名卷（docker volume ls 可见，前缀为项目名）：

卷挂载点内容
aleph-417-stack_postgres-data/var/lib/postgresql/data业务库：用户/集合/权限/告警 + FtM 实体库
aleph-417-stack_elasticsearch-data/usr/share/elasticsearch/data全文/实体索引（可重建）
aleph-417-stack_archive-data/data原始文档二进制归档（ARCHIVE_TYPE=file 默认）
aleph-417-stack_redis-data/dataRedis 持久化快照
aleph-417-stack_rabbitmq-data/var/lib/rabbitmq/队列持久化

备份策略（来源：官方安装文档 Backup 章节）：核心两件是 文档归档卷（archive-data）与 SQL 数据库（docker compose exec postgres pg_dumpall）；ES 索引可随时用 aleph reindex-full 从 FtM 实体库重建，无需备份。要换用外部对象存储（S3 兼容）承载文档归档，改 ARCHIVE_TYPE/ARCHIVE_PATH（或 S3 三件套）即可，见 《Aleph 4.1.7 配置参数详解》。

六、常用运维命令

6.1 日常管理

docker compose ps                 # 服务状态
docker compose logs -f api        # 跟看 API 日志（worker / ingest-file / elasticsearch 同理）
docker compose restart worker     # 重启单个服务（重启 worker/ingest-file 是清任务积压的第一招）
docker compose stop && docker compose up -d    # 整栈停/启（卷保留，数据不丢）

6.2 资源占用实测

docker stats --no-stream --format '{{.Name}}\t{{.MemUsage}}'

实测回显（Aleph 相关行，空闲态含一份样例数据）：

aleph-417-stack-ui-1            3.121MiB / 31.3GiB
aleph-417-stack-api-1           1.231GiB / 31.3GiB
aleph-417-stack-worker-1        248.3MiB / 31.3GiB
aleph-417-stack-ingest-file-1   869.4MiB / 31.3GiB
aleph-417-stack-rabbitmq-1      113.2MiB / 31.3GiB
aleph-417-stack-redis-1         6.586MiB / 31.3GiB
aleph-417-stack-postgres-1      41.66MiB / 31.3GiB
aleph-417-stack-elasticsearch-1 695.7MiB / 31.3GiB

合计约 3.2GiB（api 最高是 Gunicorn 6 worker 的常规水位；ingest-file 含 OCR 模型常驻约 0.9GiB）。4GB 机器不建议，8GB 可小规模使用，批量 OCR 场景建议 16GB。

6.3 版本升级

# 1. 编辑 aleph.env，将 ALEPH_TAG 改为目标稳定版（如 4.1.8 正式转正后）
#    也可直接 sed：sed -i 's/^# ALEPH_TAG=.*/ALEPH_TAG=4.1.8/' aleph.env
# 2. 拉新镜像并滚动重建（注意同步确认 ingest-file 新版本）
docker compose pull
docker compose up -d
# 3. 执行数据库/索引迁移
docker compose run --rm shell aleph upgrade

⚠️ 升级前按第五章做 pg_dumpall + 归档卷备份；跟随官方「Latest」版本号升级，不要追 rc 或未转正 tag。

七、配置文件挂载与运行形态

7.1 应用镜像内置默认值（免配置的连接参数）

应用镜像（ghcr.io/alephdata/aleph:4.1.7）的 Dockerfile 已内置全栈默认连接参数，因此 aleph.env 无需配置数据库/ES/Redis 地址（来源：仓库 4.1.7 tag Dockerfile ENV 实查）：

环境变量镜像默认值指向
ALEPH_DATABASE_URIpostgresql://aleph:aleph@postgres/alephpostgres 服务
FTM_STORE_URIpostgresql://aleph:aleph@postgres/aleph实体库与业务库同库
ALEPH_ELASTICSEARCH_URIhttp://elasticsearch:9200/elasticsearch 服务
REDIS_URLredis://redis:6379/0redis 服务
ARCHIVE_TYPE / ARCHIVE_PATHfile / /data本地归档卷

如需替换任一基础件（外置 ES、外置 S3），在 aleph.env 覆盖对应变量即可，完整参数说明见 《Aleph 4.1.7 配置参数详解》。

7.2 单容器形态说明（等价运行形态）

Aleph 是 8 服务平台，没有「单容器跑全栈」的官方形态，等价 docker run 不构成合理的部署方式。但理解单容器形态有助于排障与外置基础件改造：aleph 应用镜像可以单独启动，只要用环境变量把四个外部依赖指到可达地址：

docker run -d --name aleph-standalone \
  --env-file aleph.env \
  -e ALEPH_DATABASE_URI=postgresql://aleph:aleph@10.0.0.10:5432/aleph \
  -e ALEPH_ELASTICSEARCH_URI=http://10.0.0.11:9200/ \
  -e REDIS_URL=redis://10.0.0.12:6379/0 \
  -e RABBITMQ_URL=10.0.0.13 \
  -v aleph-archive:/data \
  -p 8000:8000 \
  ghcr.io/alephdata/aleph:4.1.7

该形态默认启动的是 Gunicorn API 进程；worker 角色（aleph worker）、ingest-file 服务仍需按需另行启动，因此生产部署一律以官方 Compose 编排为准，单容器形态仅用于连通性验证与故障定位。

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

以下问题均在本次部署中真实发生，处理过程实录。

8.1 UI 起不来：host not found in upstream "api:8000"

现象：docker compose ps 中 ui 显示 Exited (1)，API 与其他服务正常。

定位：docker compose logs ui 显示：

nginx: [emerg] host not found in upstream "api:8000" in /etc/nginx/conf.d/default.conf:22

原因：ui 的 Nginx 在启动瞬间解析 api 主机名失败——ui 与 api 的启动存在时序竞态（compose 的 depends_on 只保证「容器启动」不保证「服务就绪」）。

处置：直接重启 ui 即可（此时 api 已就绪）：

docker compose restart ui
# 确认 Up 且端口映射在列
docker compose ps ui

8.2 端口映射「失效」：curl 返回的不是 Aleph

现象：UI 映射端口 8137 后，curl http://localhost:8137/ 返回 200 但内容是一个陌生的静态页，/api/2/statistics 返回 File not found；docker compose ps 里 ui 行的 PORTS 列为空。

定位：curl -I 看响应头 Server: Algernon——宿主上另一个服务正占着 8137，Docker 端口绑定实际未生效。

处置：换一个确认空闲的宿主端口（本文用 8142），改 compose 的 ui.ports 与 aleph.env 的 ALEPH_UI_URL 后重建：

docker compose up -d ui
# 回显确认映射生效：0.0.0.0:8142->8080/tcp
docker compose ps ui

教训：映射端口前先 ss -ltn | grep <端口> 确认空闲；「UI 返回 200」不等于「Aleph 在响应」。

8.3 aleph reindex 报 No such collection: '1'

现象：按集合 ID 执行 docker compose run --rm shell aleph reindex 1 报错。

定位与处置：reindex 子命令接收的是集合 foreign_id而非数字 ID：

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)

各集合 foreign_id 用 docker compose run --rm shell aleph collections 查看（CLI 全集见 《Aleph 4.1.7 常用 CLI 命令与工具详解》）。

8.4 搜索/集合列表全部为空

现象：登录前的 API 调用（collections、entities 搜索）返回空结果。

原因：私有集合对匿名请求不可见（权限设计）。处置：按 4.6 创建管理员后登录再验证；API 脚本化访问用会话 Token 或 API Key，注意认证头格式是 Authorization: Token <jwt> 或裸 API Key 值，不是 Bearer <key>（实测 Bearer 前缀会被当作无效 Key 静默降级为匿名）。

九、参考链接