Acra 介绍与选型指南

目标：说明 Acra 的定位、两种字段加密模式，以及与 Vault、透明数据加密（TDE）、pgcrypto 的差异，给出可执行的选型结论。本文只做公开资料溯源，未在本机部署验证；版本与活跃度数据查询日期为 2026-11-02。

一、环境信息

• 文档类型：认知与选型（A1），不含本机实测。
• 版本取证日期：2026-11-02。
• 取证来源：GitHub 仓库 cossacklabs/acra 的 Releases 页、Commits 页、README，官方文档站 docs.cossacklabs.com/acra/，以及 shields.io 徽章接口返回的仓库元数据。
• 本专栏后续实测篇的运行环境：Ubuntu 26.04.1 LTS、Linux 7.0.0-38-generic x86_64、Docker 29.9.2、Docker Compose v5.6.1，AcraServer 代理端口 9393、HTTP API 端口 9090（宿主映射 8144）。
• 本文讨论的版本线：Acra 0.96.0（2024-09-09 发布）。

二、软件概述

2.1 定位

Acra 是 Cossack Labs 开发的数据库安全套件，核心目标不是"给数据库加一把锁"，而是在数据库与应用程序之间插入一个可编程的 SQL 代理，由代理完成字段级加密、解密、密钥隔离与异常访问检测。数据库最终存储的是密文，应用拿到的仍是明文，DBA 或具备数据库直连权限的人无法读取敏感字段。

它解决的是三类现实问题：

1. 数据库被拖库、备份泄露、只读副本被越权访问时，敏感列仍是密文；
2. 合规要求（个人信息、支付数据）要求"密钥与数据分离"，密钥不能和数据库放在同一台机器；
3. 需要在不改动 ORM、不重写全部 SQL 的前提下，对既有系统做字段级加密。

2.2 维护方与许可

2.3 版本线与活跃度

维护风险判断：截至 2026-11-02，距 0.96.0 发布已超过 26 个月没有新版本；代码仓库在 2025 年仍有提交，但以维护性改动为主，未见新的稳定版本。结论是低活跃、维护风险中等偏高，不宜按"快速迭代的开源项目"来规划升级节奏。生产采用前应固定版本、自行留存构建产物，并评估商业支持合同；不要依赖上游持续修复安全问题的假设。

⚠️ 注意：Acra 的版本号在配置文件中同样是必填项（version: 0.96.0），缺失会导致服务拒绝启动；因此"固定版本"不仅是运维策略，也是配置约束。

三、核心架构

3.1 组件构成

3.2 模式一：透明代理加密

数据流如下：

1. 应用使用普通数据库驱动，连接串指向 AcraServer 的 9393 端口，而不是数据库的 5432；
2. AcraServer 用同一套数据库凭据连到真实数据库；
3. AcraServer 读取 encryptor_config，识别"哪张表、哪些列"需要加密；
4. 写入时，应用提交明文 INSERT/UPDATE，AcraServer 在转发前把指定列替换为密文；
5. 读取时，AcraServer 在返回结果前把密文列解密为明文（以字节串形式回传给驱动）；
6. 数据库里始终只有密文，应用代码几乎不需要改动。

这种方式适合"已有系统、不能大改业务代码"的场景。本专栏的 《Acra Docker Compose 部署指南》 与 《Acra 0.96.0 配置参数详解》 均基于该模式实测。

3.3 模式二：客户端加密

数据流如下：

1. 应用集成 AcraWriter（或语言对应的封装库），在写入数据库前自行调用加密，得到 AcraStruct/AcraBlock 密文；
2. 应用把密文当普通二进制写入数据库，可直连数据库，也可经过 AcraServer；
3. 读取时由 AcraServer 解密，或由持有私钥的客户端自行解密；
4. 数据库、DBA、备份链路都接触不到明文，密钥只在应用侧与密钥目录中。

这种方式的加密边界更靠近业务，适合"应用可信、数据库不可信"的模型，但需要改造写入代码、处理密文的类型转换，并自行管理客户端密钥分发。

3.4 两种模式对比

四、功能特性

4.1 字段级加密

按表、按列配置加密策略，支持 acrablock（对称、体积小、速度快，0.96.0 的默认封装）与 acrastruct（非对称、体积大、可离线解密）两种封装。加密策略以 YAML 描述，支持"整表列清单 + 指定加密列"的写法。

4.2 可搜索加密

对需要等值查询的列，可生成 HMAC 盲索引（search_hmac 密钥），使 WHERE email = ... 仍可命中，同时数据库看不到明文。代价是索引列只支持等值匹配，范围查询与模糊查询不可用。

4.3 数据脱敏与令牌化

AcraServer 提供 masking（按策略返回脱敏值）与 tokenization（把敏感值替换为令牌、真实值存入独立存储）能力，用于"应用只需要部分信息"或"敏感值不应落到业务库"的场景。令牌化依赖额外的令牌存储，部署复杂度高于纯加密。

4.4 入侵检测（毒化记录）

向业务表插入特殊构造的"毒化记录"。正常业务查询不会命中它；一旦有人执行全表扫描或批量导出，AcraServer 会检测到毒化记录并记录告警、执行脚本或直接停止服务。它检测的是"异常访问模式"，不是"异常 SQL 语法"。

4.5 审计日志完整性链

开启 audit_log_enable 后，每条日志追加 integrity=<HMAC>，并用 chain=new 标记链首，后续日志依次串联。这样即使日志文件被篡改，也能发现断链。密钥为 secure_log_key，由 AcraKeymaker 生成。

4.6 密钥管理

主密钥（Acra Master Key）以环境变量 ACRA_MASTER_KEY 注入，值为 32 字节主密钥的 Base64 编码。密钥目录（keys_dir）保存客户端私钥、对称密钥、HMAC 密钥、审计密钥与毒化记录密钥。支持两种密钥库格式：v1（平铺文件，0.96.0 默认）与 v2（新格式）。具体的生成、查看、导出、迁移与销毁操作见 《Acra 0.96.0 常用 CLI 命令与工具详解》。

4.7 传输安全

AcraServer 与应用、与数据库之间都支持 TLS，tls_auth 默认值为 4（RequireAndVerifyClientCert）。关闭 TLS 时，HTTP API 会输出"未启用 TLS"的告警，生产环境应同时启用代理 TLS 与 API TLS。

4.8 数据库支持

0.96.0 以 PostgreSQL 为主，MySQL 通过 mysql_enable 开启。SQL 解析器对复杂语句、存储过程、跨库查询的支持有限；上线前必须用业务真实 SQL 做回归。

五、快速开始（官方推荐路径）

以下命令与目录结构引自官方 Getting Started 与仓库内示例，本次未在本机复现，仅用于说明官方推荐形态；可复现的实测步骤见 《Acra Docker Compose 部署指南》。

官方提供三种获取方式：

官方仓库内自带 PostgreSQL 的 Compose 样例 docker/docker-compose.pgsql-ssl-server-ssl.yml，其核心思路是：

services:
  acra-keymaker_client:
    image: "cossacklabs/acra-keymaker:${ACRA_DOCKER_IMAGE_TAG:-latest}"
    network_mode: "none"
    command: >-
      --client_id=""
      --generate_acrawriter_keys
      --keys_output_dir=/keys/acra-server
      --keys_public_output_dir=/keys/acra-server
      --keystore=v1

  acra-server:
    image: "cossacklabs/acra-server:${ACRA_DOCKER_IMAGE_TAG:-latest}"
    ports:
      - "9393:9393"
    command: >-
      --db_host=postgresql
      --keys_dir=/keys
      --tls_auth=4
      --tls_client_id_from_cert

💡 技术拓展：官方样例把"生成密钥"和"启动代理"拆成两个服务，是为了保证密钥只生成一次。若把密钥生成放在代理的启动依赖里，每次重启都会重新生成密钥并轮换旧密钥，存量数据将无法解密。本专栏的 《Acra Docker Compose 部署指南》 用 profiles + 一次性初始化任务复现了这一约束。

最小验证思路（官方文档口径）：先创建密钥目录并生成密钥，再启动 AcraServer，最后让 psql 连接 AcraServer 的 9393 端口建表、写入、读取；直接连数据库应看到密文。

六、适用场景与限制

6.1 适用场景

• 已有 PostgreSQL/MySQL 业务，想在不改代码的前提下对手机号、邮箱、身份证号等列加密；
• 数据库托管在第三方，DBA 或云厂商不应看到明文；
• 需要"异常批量导出检测"作为数据泄露的最后一道告警；
• 需要可验证的审计日志（HMAC 链）满足合规检查。

6.2 限制与风险

1. 代理是有状态单点：AcraServer 自身不提供集群/多活方案，生产需自行做进程级冗余与负载均衡。
2. SQL 兼容性有边界：复杂 SQL、存储过程、跨库 JOIN、部分 ORM 生成的语句可能解析失败；sql_parse_on_error_exit_enable 默认关闭，解析失败时行为需按业务验证。
3. 密文类型变化：透明代理模式下，加密列经代理返回时表现为字节串，客户端驱动可能显示为 \x... 十六进制；报表、导出、BI 工具需适配。
4. HTTP API 很薄：0.96.0 社区版的 HTTP API 仅提供 GET /resetKeyStorage，没有健康检查、指标、密钥查询端点；监控需靠进程存活与日志。
5. zones 已移除：zone 相关能力在 0.94 废弃、0.95 移除，旧教程中的 acra-addzone 在 0.96.0 中已不存在。
6. 版本停滞：0.96.0 之后无新版本，安全修复与数据库新版本兼容性需自行评估。
7. 运维复杂度：密钥目录权限、主密钥注入、审计密钥、毒化记录密钥、TLS 证书共同构成一条较长的信任链，任一环配置错误都会导致启动失败或数据不可解。

七、同类选型对比

7.1 对比对象

💡 技术拓展：TDE 解决的是"磁盘/备份被拿走"，不是"DBA 越权查询"；pgcrypto 解决的是"某一列存密文"，但密钥通常仍在数据库侧。Acra 的差异点是把"解密权限"从数据库搬到代理，从而改变信任边界。

7.2 量化对比表

下表按架构推理给出 1–5 分（5 为最优），不是官方性能基准：

7.3 选型结论

• 已有 PostgreSQL/MySQL 业务、只想对少量敏感列加密、且不能大改代码：选 Acra 透明代理模式。
• 需要统一密钥管理、动态数据库凭据、云原生集成：选 Vault；字段加密仍需 Acra 或应用层补齐。
• 主要威胁是磁盘/备份失窃，且接受 DBA 看到明文：TDE 成本最低。
• 只有个别列、能改 SQL、且数据库账号权限已严格隔离：pgcrypto 足够，但要避免密钥进入 SQL 日志。
• 新建系统、写入路径可控、要求数据库侧永不见明文：Acra 客户端加密模式或成熟的应用层加密库。
• 对上游持续维护、长期安全补丁有强依赖：Acra 当前节奏偏慢，应购买商业支持或准备自维护方案。

八、参考链接

1. Acra 官方文档站：https://docs.cossacklabs.com/acra/（查询日期 2026-11-02）
2. GitHub 仓库：https://github.com/cossacklabs/acra（查询日期 2026-11-02）
3. Releases 页：https://github.com/cossacklabs/acra/releases（最新稳定版 0.96.0，2024-09-09）
4. Commits 页：https://github.com/cossacklabs/acra/commits/master（最近提交 2025-12）
5. 官方 Compose 样例：https://github.com/cossacklabs/acra/blob/master/docker/docker-compose.pgsql-ssl-server-ssl.yml
6. 星标徽章：https://img.shields.io/github/stars/cossacklabs/acra.json（1.5k，2026-11-02）