Aleph 4.1.7 配置参数详解

Aleph 4.1.7 配置参数体系详解：aleph.env 全参数表、镜像内置默认值、settings.py 生效机制（改后必须重建）、外置基础件改造、ES 堆位置与验证、含 APP_TITLE 修改实测与 xref 模型内网化等 5 则排障。

Aleph数据平台ElasticsearchPython2026/10/24

Aleph 4.1.7 配置参数详解

目标：系统讲清 Aleph 4.1.7 的配置参数体系——官方环境变量模板 aleph.env 的全部参数、应用镜像内置默认值、settings.py 读取与生效机制，并给出生产模板与常见坑。本文参数名与默认值逐一核对自仓库 4.1.7 tag 源码（aleph/settings.py、aleph.env.tmpl、Dockerfile），生效行为在实测部署机上验证（环境见第一章）。

一、环境信息

项值
操作系统Ubuntu 22.04（内核 6.8.0-138-generic）
Aleph4.1.7（官方 Docker 镜像 ghcr.io/alephdata/aleph:4.1.7）
部署形态官方 Docker Compose 全栈 8 服务（部署过程见 《Aleph Docker Compose 部署指南》）
对外地址http://192.168.146.128:8142/
实测日期2026-10-24
核对来源https://github.com/alephdata/aleph/blob/4.1.7/aleph/settings.py（参数定义）；https://github.com/alephdata/aleph/blob/4.1.7/aleph.env.tmpl（官方模板）；https://github.com/alephdata/aleph/blob/4.1.7/Dockerfile（镜像内置默认值）

二、前置条件

  • 已按部署指南完成 Aleph 4.1.7 全栈部署并能登录 UI；
  • 了解 aleph.env 的位置：与 docker-compose.yml 同目录，由官方部署编排在启动 api / worker / ingest-file / shell 四个服务时通过 env_file 机制注入进程环境；
  • 参数定义的权威位置是 aleph/settings.py（AppSettings 类），每个参数的读取代码形如 env.get("ALEPH_XXX", 默认值)，本文表格中的「默认值」即来源于此。

三、参数查看与修改方式

3.1 生效机制（两段式）

Aleph 的配置链路是固定的两段式，理解它才能正确改配置：

  1. 注入段：aleph.env 的每一行 KEY=VALUE 在服务启动时注入对应进程的环境（env_file 机制，作用于 api / worker / ingest-file / shell 四个服务）；
  2. 读取段：进程启动时 aleph/settings.py 用 env.get()/env.to_bool() 从环境读取参数初始化单例配置——启动后不再重读。

因此修改方式只有一个固定套路：改 aleph.env → 重建受影响的服务进程 → 验证。改完不重启，参数不会生效。

两个特例要区分：

  • ES 的 JVM 堆（ES_JAVA_OPTS）不是 Aleph 参数，写在编排文件 elasticsearch 服务的 environment 段（位置与验证方法见部署指南 4.3，实测 -Xms256m -Xmx256m 已生效）；
  • worker 并发（WORKER_THREADS）同样通过 aleph.env 注入，但它由 servicelayer 队列框架读取（见 5.6.3）。

3.2 查看方式

方式一：看模板与实际注入值。 官方模板 aleph.env.tmpl 是参数字典；运行中的实际注入值在部署目录核对：

docker compose exec api env | grep -E '^ALEPH_' | sort

实测回显（本部署实例，共 22 项 ALEPH_ 前缀参数，节选）：

ALEPH_APP_NAME=aleph
ALEPH_APP_TITLE=Aleph
ALEPH_DATABASE_URI=postgresql://aleph:aleph@postgres/aleph
ALEPH_ELASTICSEARCH_URI=http://elasticsearch:9200/
ALEPH_FTM_COMPARE_MODEL_URI=https://public.data.occrp.org/develop/models/xref/glm_bernoulli_2e_wf-v0.4.1.pkl
ALEPH_OCR_DEFAULTS=eng
ALEPH_SECRET_KEY=3f2a8d9c1b7e5f4a6d8c2b9e7f1a3d5c
ALEPH_UI_URL=http://192.168.146.128:8142/
ALEPH_WORD_FREQUENCY_URI=https://public.data.occrp.org/develop/models/word-frequencies/word_frequencies-v0.4.1.zip

💡 注意其中两项未出现在 aleph.env：ALEPH_FTM_COMPARE_MODEL_URI（xref 相似度模型）与 ALEPH_WORD_FREQUENCY_URI（词频模型）是镜像内置的 OCCRP 官方模型地址，内网隔离环境可用自己的镜像服务地址覆盖（见 5.4.4）。

方式二：公开元数据接口。 /api/2/metadata 返回不含敏感值的运行时配置子集（UI 标题、语言、schema 体系等），适合脚本巡检：

curl -s http://localhost:8142/api/2/metadata | python3 -c "import json,sys; print(json.load(sys.stdin)['app']['title'])"

实测回显：

Aleph

方式三：源码核对。 有默认值拿不准时，以 4.1.7 tag 的 aleph/settings.py 为准（各参数「默认值」列的出处）。

3.3 修改方式（实测：改 ALEPH_APP_TITLE）

以修改站点标题为完整实测案例：

# 1. 编辑 aleph.env
sed -i 's/^ALEPH_APP_TITLE=Aleph$/ALEPH_APP_TITLE=Aleph Lab/' aleph.env

# 2. 重建读取该参数的服务（env_file 变化后 compose 会识别并重建）
docker compose up -d api worker ingest-file

实测回显（compose 自动重建三个服务）：

 Container aleph-417-stack-worker-1 Recreate
 Container aleph-417-stack-worker-1 Recreated
 Container aleph-417-stack-api-1 Recreate
 Container aleph-417-stack-api-1 Recreated
 Container aleph-417-stack-worker-1 Started
 Container aleph-417-stack-api-1 Started

# 3. 验证生效
curl -s http://localhost:8142/api/2/metadata | python3 -c "import json,sys; print(json.load(sys.stdin)['app']['title'])"

实测回显：

Aleph Lab

⚠️ 三段都必须做：只改文件不重建是最常见的「参数没生效」原因（排障见 7.1）。涉及 ES/数据库连接的参数修改会短暂中断服务，请在维护窗口操作。

四、参数总览

按功能域分组的一览表（★=部署后必须设置；默认值来源：aleph.env.tmpl / settings.py / Dockerfile）：

分类参数默认值说明
★密钥ALEPH_SECRET_KEY无（必填）会话签名密钥，openssl rand -hex 24 生成
应用ALEPH_APP_TITLEAlephUI 站点名称
应用ALEPH_APP_NAMEaleph实例 slug（用于索引前缀、队列名），改后注意存量索引/队列不迁移
应用ALEPH_APP_BANNER / ALEPH_APP_MESSAGES_URL无全局横幅公告（静态文本 / JSON 接口二选一）
应用ALEPH_LOGO / ALEPH_FAVICON内置静态图站点品牌图
入口ALEPH_UI_URLhttp://localhost:8080/★对外访问地址（决定外链与回跳）
入口ALEPH_FORCE_HTTPS / ALEPH_URL_SCHEMEfalse / http反代 HTTPS 时设 true 或 scheme=https
入口ALEPH_CORS_ORIGINS* （|分隔列表）API 跨域白名单
认证ALEPH_SINGLE_USERfalse单人模式（免登录全管理员，实验用）
认证ALEPH_PASSWORD_LOGINtrue密码登录开关
认证ALEPH_OAUTHfalseOAuth/OIDC 登录总开关
认证ALEPH_OAUTH_KEY / ALEPH_OAUTH_SECRET无OAuth 客户端凭据
认证ALEPH_OAUTH_METADATA_URL无OIDC 发现地址（Google/KeyCloak/Azure/Cognito）
认证ALEPH_OAUTH_HANDLERoidcOIDC 处理器
认证ALEPH_OAUTH_SCOPEopenid email profileOIDC scope
认证ALEPH_OAUTH_ADMIN_GROUPsuperuser该组成员自动授予 admin
认证ALEPH_SESSION_EXPIRE60000（单人 800000）秒会话过期
认证ALEPH_REQUIRE_LOGGED_INfalse全站强制登录
认证ALEPH_ADMINS无（冒号分隔邮箱）指定邮箱自动为管理员
认证ALEPH_ROLE_INACTIVE180 天未活跃账号判定阈值
数据ALEPH_DATABASE_URI镜像内置 postgresql://aleph:aleph@postgres/aleph业务库（用户/集合/权限）
数据FTM_STORE_URI同上FtM 实体库（默认与业务库同库）
数据TAGS_DATABASE_URI取前两者之一ingest-file 文档缓存库
数据ALEPH_ELASTICSEARCH_URI镜像内置 http://elasticsearch:9200/ES 地址
数据ELASTICSEARCH_TLS_CA_CERTS 等 4 项无外置 ES 的 mTLS 证书
数据ARCHIVE_TYPE / ARCHIVE_PATHfile / /data文档归档：本地目录或 s3
数据ARCHIVE_BUCKET / AWS_REGION / AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY无S3 归档参数（IAM Role 时留空后两项）
队列REDIS_URL镜像内置 redis://redis:6379/0Redis（缓存/统计）
队列RABBITMQ_URL镜像内置 rabbitmqRabbitMQ 主机
队列RABBITMQ_USERNAME / RABBITMQ_PASSWORDguest / guest队列凭据
队列ALEPH_RABBITMQ_MAX_PRIORITY10队列优先级上限
队列ALEPH_RABBITMQ_QOS_INDEX_QUEUE100index 队列预取
队列ALEPH_RABBITMQ_QOS_XREF_QUEUE 等 8 项1xref/reindex/export 等队列预取
队列WORKER_THREADSCPU 核数worker 线程数（0=单线程多进程）
索引ALEPH_INDEX_PREFIX=APP_NAMEES 索引名前缀
索引ALEPH_INDEX_WRITE / ALEPH_INDEX_READv1 / 同 write写/读索引版本（蓝绿重建用）
索引ALEPH_INDEX_REPLICAS0ES 副本数（单节点必须 0）
索引ALEPH_INDEXING_BATCH_SIZE100批量索引块大小
索引ALEPH_INDEXING_TIMEOUT10 秒索引超时
索引ALEPH_XREF_SCROLL / ALEPH_XREF_SCROLL_SIZE5m / 1000xref 滚动查询参数
文档ALEPH_OCR_DEFAULTSengTesseract OCR 默认语言包
文档ALEPH_LANGUAGESen:de:fr:es:tr:ar…语言检测范围（冒号分隔）
文档ALEPH_DEFAULT_LANGUAGEen实体名/文本缺省语言
文档ALEPH_INGEST_PIPELINEanalyzeingest 后续阶段
文档ALEPH_RESULT_HIGHLIGHTtrue搜索命中片段高亮
文档ALEPH_MAX_EXPAND_ENTITIES200图谱展开上限
检索ALEPH_API_RATE_LIMIT / ALEPH_API_RATE_WINDOW30 / 15 秒API 限流
站点ALEPH_PAGES_PATH应用内 pages 目录自定义静态页目录（公开门户）
邮件ALEPH_MAIL_FROM / ALEPH_MAIL_HOSTaleph@domain.com / localhost发件人与 SMTP 主机
邮件ALEPH_MAIL_PORT / ALEPH_MAIL_TLS / ALEPH_MAIL_SSL25 / true / falseSMTP 端口与加密
邮件ALEPH_MAIL_USERNAME / ALEPH_MAIL_PASSWORD / ALEPH_MAIL_DEBUG无SMTP 凭据与调试
运维ALEPH_DEBUGfalse调试模式（不安全，勿用于生产）
运维ALEPH_PROFILEfalse请求性能分析
运维ALEPH_CACHE=非 DEBUGHTTP 缓存
运维ALEPH_MAINTENANCEfalse只读维护模式（禁写入操作）
运维ALEPH_WORKER_STAGESworker 全阶段worker 只跑指定阶段（分角色扩容用）
运维ALEPH_NOTIFICATIONS_DELETE90 天通知保留期
监控LOG_FORMATTEXT（镜像内置）日志格式 TEXT/JSON
监控SENTRY_DSN / SENTRY_ENVIRONMENT空Sentry 上报
xref 模型ALEPH_FTM_COMPARE_MODEL_URIOCCRP 公网 pkl 地址xref 相似度模型
xref 模型ALEPH_WORD_FREQUENCY_URIOCCRP 公网 zip 地址词频模型

💡 参数存在两个通用扩展前缀：ALEPH_STRING_CONFIG_PREFIX（字符串配置）与 ALEPH_JSON_CONFIG_PREFIX（JSON 配置），允许以外部值批量覆盖任意 Flask 配置项，属于高级用法（来源：settings.py 尾部实现），常规运维不建议。

五、核心参数分类详解

5.1 必改参数（两件套）

ALEPH_SECRET_KEY：所有会话签名的根密钥。首次部署必须用 openssl rand -hex 24 生成；更换后全部登录态失效（影响可用性，不影响数据）。绝不要用官方示例值上生产。

ALEPH_UI_URL：实例对外入口。它影响：UI 内生成的分享/回跳链接、API 客户端拼 URL 的基准、OAuth 回调。必须带末尾 /，且与浏览器实际访问地址完全一致（本实测实例为 http://192.168.146.128:8142/）。反代 HTTPS 时改为公网域名并配合 5.2 的 FORCE_HTTPS。

5.2 连接与存储参数（外置基础件改造入口）

镜像内置默认值（来源：Dockerfile ENV，本指南实测 docker compose exec api env 已复核）：

参数内置默认值
ALEPH_DATABASE_URIpostgresql://aleph:aleph@postgres/aleph
FTM_STORE_URI（镜像未显式内置，运行时取 ALEPH_DATABASE_URI）
ALEPH_ELASTICSEARCH_URIhttp://elasticsearch:9200/
REDIS_URLredis://redis:6379/0
ARCHIVE_TYPE / ARCHIVE_PATHfile / /data

改造场景：

  • 外置 PostgreSQL：ALEPH_DATABASE_URI=postgresql://<user>:<pass>@<host>/<db>；同时决定 FTM_STORE_URI 是否分库（实体库写放大明显，大规模实例建议独立库实例，连接串同格式）；
  • 外置 Elasticsearch：ALEPH_ELASTICSEARCH_URI=https://es.internal:9200；自签名/mTLS 时用模板里的 ELASTICSEARCH_TLS_CA_CERTS（CA）、ELASTICSEARCH_TLS_CLIENT_CERT/KEY（客户端证书）、ELASTICSEARCH_TLS_VERIFY_CERTS=1；外置集群务必把 ALEPH_INDEX_REPLICAS 调为集群合理值；
  • S3 归档：ARCHIVE_TYPE=s3 + ARCHIVE_BUCKET + AWS_REGION，凭据两件（AWS_ACCESS_KEY_ID/SECRET）留空则走 IAM Role——这是实例「磁盘不随数据量膨胀」的关键改造点；
  • RabbitMQ 凭据：官方镜像默认 guest/guest 仅限本机使用，生产更换 RABBITMQ_USERNAME/PASSWORD 并同步改队列服务侧。

5.3 认证与登录参数

  • 密码登录（ALEPH_PASSWORD_LOGIN=true）是最简路径，配合 aleph createuser 建号（CLI 见系列 CLI 篇）；
  • OIDC 单点登录：ALEPH_OAUTH=true + ALEPH_OAUTH_KEY/SECRET + ALEPH_OAUTH_METADATA_URL（Google/KeyCloak/Azure/Cognito 的 well-known 地址，模板中有现成示例）；ALEPH_OAUTH_ADMIN_GROUP=superuser 表示 OIDC 组名匹配者自动成为管理员——这是生产环境最省运维的组合（账号生命周期交给 IdP）；
  • ALEPH_SESSION_EXPIRE 默认 60000 秒（约 16.7 小时），配合 4.1 的「API Key 90 天过期」策略，长任务脚本要做好 Key 轮换或改用会话续期；
  • ALEPH_ADMINS 支持冒号分隔邮箱白名单自动授予管理员，适合密码登录场景。

5.4 UI 与站点参数

  • ALEPH_APP_TITLE：站点名，改动即生效（修改实测见 3.3）；
  • ALEPH_APP_BANNER：全局公告横幅（如「系统维护中」），ALEPH_APP_MESSAGES_URL 可换成 JSON 接口动态下发；
  • ALEPH_UI_LANGUAGES：界面语言集（settings.py 内置默认含 ar/de/en/es/fr/ru 等，UI 支持 RTL）；ALEPH_DEFAULT_LANGUAGE=en 是文档缺省语言；
  • ALEPH_PAGES_PATH：公开门户静态页目录（配合发布功能做站点首页/帮助页）；
  • ALEPH_LOGO/ALEPH_FAVICON：品牌图（静态路径或 URL）；
  • xref 模型地址（隐藏配置）：ALEPH_FTM_COMPARE_MODEL_URI 与 ALEPH_WORD_FREQUENCY_URI 默认指向 OCCRP 公网模型。内网隔离部署执行 xref 会因无法下载模型失败——用自建镜像源覆盖这两个地址是必要动作（实测发现点：这两个变量未出现在官方 aleph.env.tmpl，仅存在于镜像内置环境）。

5.5 文档处理与检索参数

  • ALEPH_OCR_DEFAULTS=eng：OCR 语言包，中文文档建议 chi_sim+eng（语言包需 ingest-file 镜像内含，官方镜像已带常用包集合）；
  • ALEPH_LANGUAGES：语言检测范围（冒号分隔），扩大范围会增加 analyze 阶段开销；
  • ALEPH_RESULT_HIGHLIGHT=true：命中片段高亮；ALEPH_MAX_EXPAND_ENTITIES=200：图谱单次展开实体上限（图谱页卡顿时调低）；
  • xref 参数：ALEPH_XREF_SCROLL=5m（滚动视图保持时长）、ALEPH_XREF_SCROLL_SIZE=1000（每分片批大小），大库跑 xref 前可按官方默认先不调，观察 ES 负载再动。

5.6 运维与性能参数

5.6.1 维护与缓存

  • ALEPH_MAINTENANCE=true：只读模式（4.1.6 起权限模型完善），升级/迁移窗口开启；
  • ALEPH_CACHE：HTTP 缓存，默认非 DEBUG 即开；
  • ALEPH_DEBUG：只排障临时开，生产禁用（会暴露调试信息）。

5.6.2 索引与队列调优

  • ALEPH_INDEX_WRITE/READ：支持蓝绿重建——写新版本索引（v2），完成后把 READ 切到 v2，实现零停机重索引；
  • ALEPH_RABBITMQ_QOS_* 系列：各队列预取数。index 队列默认 100（吞吐优先），xref/reindex/export 等重任务队列默认 1（独占优先）——这一组默认值本身就是官方调优结论，动手前先理解它。

5.6.3 WORKER_THREADS（worker 并发）

servicelayer 队列框架的线程数，默认=CPU 核数；0 表示禁用线程改为每进程一个 worker。扩容方式是增加 worker 服务副本数（官方安装文档「Scaling workers」章节同款思路）：大文档 OCR 瓶颈时优先加 ingest-file 资源与 worker 副本，而不是无脑调线程。

5.6.4 ES 的 JVM 堆（ES_JAVA_OPTS）

Aleph 自身是 Python 进程无 JVM，唯一的 JVM 是内置 Elasticsearch：堆大小在编排文件 elasticsearch 服务的 environment 段设置（不是 aleph.env）：

environment:
  - discovery.type=single-node
  - ES_JAVA_OPTS=-Xms256m -Xmx256m

本实例实测验证：进入 elasticsearch 服务查看进程参数，-Xms256m -Xmx256m 已生效（完整命令与回显见部署指南 4.3）。一般取宿主内存的一半、512MB～4GB 区间，Xms=Xmx 避免运行时扩堆抖动。

5.7 邮件与监控参数

  • 邮件驱动两类功能：账号密码找回与搜索告警通知。不配置（默认空 HOST）时这两类功能静默不工作，其余功能不受影响；ALEPH_MAIL_PORT=25/TLS=true 默认值对应裸 SMTP over STARTTLS 场景，对接 587/465 端口商服时改 PORT 并核对 TLS/SSL 组合；
  • LOG_FORMAT=TEXT|JSON：JSON 便于日志采集器解析；SENTRY_DSN/ENVIRONMENT：错误上报，内网可不配。

六、生产配置模板

内网生产（密码登录 + 本地归档 + 中文文档支持）推荐基线：

# ==== 必改 ====
ALEPH_SECRET_KEY=<openssl rand -hex 24 生成>
ALEPH_UI_URL=https://aleph.example.org/

# ==== 应用 ====
ALEPH_APP_TITLE=Aleph
ALEPH_APP_NAME=aleph
ALEPH_FORCE_HTTPS=true

# ==== 登录 ====
ALEPH_SINGLE_USER=false
ALEPH_PASSWORD_LOGIN=true
ALEPH_ADMINS=admin@example.org

# ==== 中文文档支持 ====
ALEPH_OCR_DEFAULTS=chi_sim+eng
ALEPH_DEFAULT_LANGUAGE=zh
# ALEPH_LANGUAGES=en:zh  （按需扩大）

# ==== 邮件（告警/找回密码必需）====
ALEPH_MAIL_FROM=aleph@example.org
ALEPH_MAIL_HOST=smtp.example.org
ALEPH_MAIL_USERNAME=aleph@example.org
ALEPH_MAIL_PASSWORD=<SMTP 密码>
ALEPH_MAIL_PORT=587
ALEPH_MAIL_TLS=true

# ==== 运维 ====
ALEPH_DEBUG=false
ALEPH_MAINTENANCE=false
LOG_FORMAT=JSON

# ==== 内网隔离：xref 模型改自建源 ====
# ALEPH_FTM_COMPARE_MODEL_URI=https://models.internal/aleph/glm_bernoulli_2e_wf-v0.4.1.pkl
# ALEPH_WORD_FREQUENCY_URI=https://models.internal/aleph/word_frequencies-v0.4.1.zip

同时把 ES 堆约束在编排文件（见 5.6.4），并按部署指南做数据卷备份。官方完整参数注释版本以 aleph.env.tmpl 为准。

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

7.1 改了 aleph.env 没生效

现象：改完参数，页面/接口行为不变。 原因：settings.py 只在进程启动时读环境（3.1 两段式）。 处置：docker compose up -d api worker ingest-file 重建服务（compose 检测到 env_file 变化会自动 Recreate）。本实测以 ALEPH_APP_TITLE 验证了完整闭环（3.3 回显）。

7.2 内网环境 xref 报错/无结果

现象：xref 任务失败，日志出现对 public.data.occrp.org 的网络错误。 原因：xref 模型（比较模型 + 词频模型）默认从 OCCRP 公网下载（镜像内置地址见 5.4）。 处置：自建模型源并覆盖 ALEPH_FTM_COMPARE_MODEL_URI、ALEPH_WORD_FREQUENCY_URI 两变量后重建。

7.3 中文文档 OCR 出来是空的

原因：ALEPH_OCR_DEFAULTS=eng 时 Tesseract 只装英文语言包模型思路处理，中文页面识别为乱噪声。 处置：ALEPH_OCR_DEFAULTS=chi_sim+eng 并重建 ingest-file/worker；存量文档用 aleph reingest <集合foreign_id> 重跑摄取（CLI 见系列 CLI 篇）。

7.4 API 脚本调用返回 401/空数据

原因：认证头格式错误。Aleph 接受 Authorization: Token <jwt>（登录会话）或裸 API Key 值（Authorization: <api_key>）；加 Bearer 前缀会被当作无效 Key 静默降级为匿名（实测踩点）。另外 4.1 起 API Key 默认不发放、90 天过期。

7.5 单节点 ES 副本报黄

现象：ES 索引健康 yellow。 原因：ALEPH_INDEX_REPLICAS 非 0 时单节点无法分配副本。 处置：保持默认 0（settings.py 默认即 0，官方为单节点部署预设）；外置多节点集群才调大。

八、参考链接