Acra 0.96.0 配置参数详解

目标：把 AcraServer 0.96.0 的配置体系拆成"怎么查、怎么改、有哪些参数、生产怎么写"，并对关键参数给出本机实测行为。本文命令与回显均来自本机运行中的 AcraServer 0.96.0。

一、环境信息

• 操作系统：Ubuntu 26.04.1 LTS，内核 Linux 7.0.0-38-generic x86_64。
• Docker：29.9.2；Docker Compose：v5.6.1。
• AcraServer：0.96.0；Acra Tools：0.96.0。
• 数据库：PostgreSQL 16，库名 testdb，用户 admin。
• 代理监听：9393（应用接入）；HTTP API：9090（宿主映射 8144）。
• 密钥目录：/opt/data/quzuo/tmp/acra/keys（权限 700），密钥库格式 v1。
• 加密策略：/opt/data/quzuo/tmp/acra/encryptor.yaml，封装类型 acrablock。

二、前置条件

1. 已完成 AcraServer 的部署，代理能正常连接数据库（步骤见 《Acra Docker Compose 部署指南》）。
2. 密钥目录已生成且权限为 700。
3. 修改配置后需重启代理；AcraServer 不热加载配置文件。
4. 生产环境修改前先备份 keys 目录与当前配置文件。

三、参数查看与修改方式

3.1 查看全部参数与默认值

docker compose run --rm --entrypoint /acra-server acra-server --help

输出较长，按关键字过滤更实用：

docker compose run --rm --entrypoint /acra-server acra-server --help 2>&1 \
  | grep -A1 -E -- '--(db_host|db_port|keys_dir|incoming_connection_port|http_api_enable|audit_log_enable)$'

实测回显（节选）：

  --audit_log_enable
    	Enable audit log functionality
  --db_host
    	Host to db
  --db_port
    	Port to db (default 5432)
  --http_api_enable
    	Enable HTTP API. Use together with --http_api_tls_transport_enable whenever possible.
  --incoming_connection_port
    	Port for AcraServer (default 9393)
  --keys_dir
    	Folder from which will be loaded keys (default ".acrakeys")

--dump_config 可导出一份带注释的 YAML 模板，作为编写配置文件的起点。导出内容覆盖全部参数，但不会回显当前命令行传入的值，不要把导出模板误当作当前生效配置。

3.2 修改方式一：命令行参数

适合少量参数或临时验证。《Acra Docker Compose 部署指南》 即采用这种方式，例如：

--db_host=postgres --db_port=5432 --keys_dir=/keys \
--encryptor_config_file=/config/encryptor.yaml \
--incoming_connection_port=9393 --http_api_enable --audit_log_enable

3.3 修改方式二：YAML 配置文件

适合参数多、需要版本化管理的生产环境。最小可用配置：

version: 0.96.0
db_host: postgres
db_port: 5432
keys_dir: /keys
client_id: client
encryptor_config_file: /config/encryptor.yaml
incoming_connection_port: 9393
http_api_enable: true
http_api_tls_transport_enable: false
audit_log_enable: true
log_to_console: true
v: true

启动时用 --config_file 指定：

docker compose run --rm --entrypoint /acra-server acra-server \
  --config_file=/config/server.yaml

⚠️ 注意：version 是配置文件的必填首字段。实测缺失时服务直接退出：

time="2026-11-02T12:40:44Z" level=error msg="Can't parse config" code=508 error="config hasn't version key"

补上 version: 0.96.0 后，服务正常加载配置、初始化密钥库并监听 9393。

3.4 优先级与生效方式

• 命令行参数优先于配置文件中的同名项；配置文件提供"默认值集合"。
• 环境变量 ACRA_MASTER_KEY 独立于配置文件，始终由进程环境注入。
• 配置在进程启动时读取一次，修改后必须重启。
• 加密策略文件由 encryptor_config_file 单独指定，与主配置分离。

四、参数总览

下表按用途归类，默认值取自 0.96.0 的配置模板与本机 --help 回显。

五、核心参数分类详解

5.1 数据库连接

db_host、db_port 必填（除非用连接字符串）。postgresql_enable 与 mysql_enable 决定 SQL 解析器与协议适配；两者不要同时开启。实测只开启 PostgreSQL 时，代理能正确转发 CREATE TABLE、INSERT、SELECT。

5.2 监听端口与 HTTP API

应用接入端口由 incoming_connection_port 控制，默认 9393。HTTP API 端口由 incoming_connection_api_port 控制，默认 9090，需要 http_api_enable 显式开启。

0.96.0 的 API 能力很薄：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8144/resetKeyStorage

实测回显：

HTTP 200

访问未定义路径：

curl -s -w '\nHTTP %{http_code}\n' http://127.0.0.1:8144/health

incorrect request
HTTP 404

开启 API 但未启用 TLS 时，启动日志会给出告警：

level=warning msg="HTTP API server is used without TLS. Consider using TLS whenever possible." code=100

💡 技术拓展：AcraServer 的"健康检查"没有 HTTP 端点，运维监控可用两种替代：进程存活探针（检查 9393 是否可建立 TCP 连接），或直接观察日志中的 Start listening connections 与 Handle client's connection。不要把 /health 接进监控。

5.3 密钥库

• keys_dir：代理只读挂载即可；密钥生成任务需要写权限。
• client_id：决定默认使用哪一组客户端密钥。透明代理模式下，策略文件未指定 client_id 时使用该默认值。
• keystore：v1 为平铺文件（0.96.0 默认），v2 为新格式；两种格式不可混用。
• keystore_encryption_type：env_master_key（默认）、kms_encrypted_master_key、vault_master_key、kms_per_client。
• keystore_cache_size：默认 1000 条，0 不限制，-1 关闭缓存；高并发场景建议保留默认值，避免每次请求都解密密钥文件。
• keystore_cache_on_start_enable：启动时把密钥预加载进缓存；实测开启后日志出现 Cached keystore on start successfully。

密钥目录权限实测要求 700，否则：

level=error msg="Keystore folder has an incorrect permissions -rwxr-xr-x, expected: -rwx------"

5.4 加密策略

encryptor_config_file 指向策略 YAML。策略结构：

defaults:
  crypto_envelope: acrablock

schemas:
  - table: customers
    columns:
      - id
      - full_name
      - email
      - phone
      - note
    encrypted:
      - column: email
      - column: phone

• defaults.crypto_envelope：acrablock 为对称封装，密文短；acrastruct 为非对称封装，可离线解密。
• schemas[].table：表名；columns 为整行列清单，encrypted 为需要加密的子集。
• 每个 encrypted 项可加 client_id，为不同客户端使用不同密钥；不写则用全局默认。
• 可搜索加密需要额外的 HMAC 密钥与策略配置；acrablock 适合等值查询，范围查询无法保持可用。
• zones 相关配置在 0.94 废弃、0.95 移除，0.96.0 不再接受 zone_id，旧配置必须清理。

5.5 TLS

tls_auth 默认 4，即要求并校验客户端证书。为代理配置 TLS 需要同时提供：

tls_cert: /ssl/acra-server.crt
tls_key: /ssl/acra-server.key
tls_ca: /ssl/ca.crt
tls_auth: 4

实测证书路径不存在时启动失败：

time="2026-11-02T12:43:53Z" level=info msg="Configuring transport..."
time="2026-11-02T12:43:53Z" level=error msg="Configuration error: can't create application TLS config" code=532 error="open /nonexistent.crt: no such file or directory"

连接数据库的 TLS 由 tls_client_cert、tls_client_key、tls_client_ca 控制；若数据库强制 SSL，而代理未配置对应证书，数据库连接会失败。

5.6 审计日志

audit_log_enable: true 后，每条日志尾部追加 integrity=<HMAC>，链首带 chain=new。审计日志依赖 secure_log_key（由 AcraKeymaker 生成）。实测日志：

level=info msg="Command complete" command=SimpleQuery integrity=fd5ff80a68f74eac7b6261d079d7d4360e4ea4b443616da0dc6cfb269fca2655

logging_format 可选 plaintext、json、CEF；集中采集时建议 json。log_to_file 为空时输出到标准错误，由编排层收集。

⚠️ 注意：审计日志的完整性链只能证明"日志未被无密钥篡改"，不能替代外部日志防篡改存储。生产应把日志实时投递到独立日志系统，并与 secure_log_key 分开保管。

5.7 入侵检测

三个参数决定命中毒化记录后的动作：

毒化记录由 AcraPoisonRecordMaker 生成，再植入业务表；具体用法见 《Acra 0.96.0 常用 CLI 命令与工具详解》。

5.8 可观测性与调试

• incoming_connection_prometheus_metrics_string：为 /metrics 提供监听地址（单独端口/URL）。
• jaeger_agent_endpoint、jaeger_collector_endpoint：导出链路追踪。
• v / d / ds：详细日志、调试日志、HTTP 调试服务；生产不要长期开启 d，日志会包含 SQL 与连接细节。

5.9 外部存储与集成

• Redis：redis_host_port 配合 redis_db_keys / redis_db_tokens，可把密钥或令牌放到集中存储；不配置时密钥落本地目录、令牌用内存存储。
• Consul：encryptor_config_storage_type: consul + consul_connection_api_string，可从 Consul KV 拉取策略。
• KMS/Vault：keystore_encryption_type 选择主密钥来源，配合 kms_type、vault_connection_api_string 等参数。使用这些集成前，先确认网络、证书与凭据注入方式。

六、生产配置模板

适用场景：16 GB 内存、NVMe SSD、OLTP 业务、PostgreSQL 主库、单实例 AcraServer 前置。

version: 0.96.0

db_host: 10.0.0.20
db_port: 5432
postgresql_enable: true
mysql_enable: false

keys_dir: /keys
client_id: client
keystore: v1
keystore_encryption_type: env_master_key
keystore_cache_size: 1000
keystore_cache_on_start_enable: true

encryptor_config_file: /config/encryptor.yaml
encryptor_config_storage_type: filesystem

incoming_connection_host: 0.0.0.0
incoming_connection_port: 9393
incoming_connection_close_timeout: 10

http_api_enable: true
http_api_tls_transport_enable: true
incoming_connection_api_port: 9090

tls_cert: /ssl/acra-server.crt
tls_key: /ssl/acra-server.key
tls_ca: /ssl/ca.crt
tls_auth: 4
tls_client_id_from_cert: true

tls_client_cert: /ssl.acra-server/client.crt
tls_client_key: /ssl.acra-server/client.key
tls_client_ca: /ssl.ca/ca.crt

audit_log_enable: true
logging_format: json
log_to_console: false
log_to_file: /var/log/acra/acra-server.log

poison_detect_enable: true
poison_shutdown_enable: false

sql_parse_on_error_exit_enable: false

要点：

1. http_api_tls_transport_enable: true 必须与 API 证书配套；只改布尔值而不提供证书会导致启动失败。
2. 数据库连接启用 TLS 时，tls_client_cert 等三项要指向真实文件。
3. 审计日志写文件时，确保挂载目录可写，否则进程无法启动。
4. 生产不建议开启 d、ds；v 仅在排障期间临时开启。
5. 所有证书、密钥路径都用绝对路径，避免工作目录变化导致加载失败。

七、常见问题

7.1 配置文件缺少 version

level=error msg="Can't parse config" code=508 error="config hasn't version key"

在 YAML 第一行补 version: 0.96.0。

7.2 TLS 证书路径不存在

level=error msg="Configuration error: can't create application TLS config" code=532 error="open /nonexistent.crt: no such file or directory"

确认挂载路径与配置中的绝对路径一致；证书与私钥必须成对存在。

7.3 修改配置后不生效

AcraServer 只在启动时读取配置。修改后执行：

docker compose restart acra-server

7.4 开启审计日志后启动失败

检查 secure_log_key 是否存在、密钥目录权限是否为 700、日志文件路径是否可写。审计日志密钥缺失时，代理无法生成 HMAC 链。

7.5 HTTP API 无法访问

• 确认 http_api_enable: true 且端口映射正确；
• 确认访问路径是 /resetKeyStorage，其他路径必然 404；
• 开启 API TLS 后必须用 https:// 访问，并用对应 CA 校验。

7.6 加密列没有生效

按顺序排查：策略文件是否被加载（日志 Encryptor configuration loaded）、表名/列名是否完全匹配、encrypted 是否包含目标列、实际连接是否走代理端口 9393（而不是数据库端口）。

八、参考链接

1. Acra 官方文档站：https://docs.cossacklabs.com/acra/（查询日期 2026-11-02）
2. 官方配置示例：https://github.com/cossacklabs/acra/blob/master/configs/acra-server.yaml
3. 加密策略示例：https://github.com/cossacklabs/acra/blob/master/configs/acra-encryptor.example.yaml
4. 密钥管理文档：https://docs.cossacklabs.com/acra/security-controls/key-management/