Infisical v0.166.9 配置参数详解

目标：系统梳理 Infisical v0.166.9 自托管的全部常用配置参数（收敛在 .env 环境变量一处），按「通用平台 / CORS / 数据层 / 连接池 / 审计日志 / SMTP / 认证与机器身份 / 可观测」逐项给出含义、官方默认值与生效方式，参数行为均经真实部署实测或官方文档实查（查询日期 2026-10-21），帮助读者一次配准生产实例。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（x86_64）
• Infisical：v0.166.9（infisical/infisical:v0.166.9，2026-10-21 GitHub Releases 最新稳定标签）
• 部署形态：官方 Docker Compose 方案（主服务 + PostgreSQL 14 + Redis 7，.env 统一注入），部署过程见《Infisical v0.166.9 Docker Compose 部署指南》
• 参数来源：随部署镜像发布的 .env.example（v0.166.9 main 分支）、官方环境变量文档 infisical.com/docs/self-hosting/configuration/envars、镜像内配置模块 lib/config/env.mjs 反查、以及本文实测部署的行为验证
• 标注约定：【实测】= 本文部署环境中验证过实际行为；【实查】= 官方文档/示例文件实查（2026-10-21）

二、前置条件

1. 已按《Infisical v0.166.9 Docker Compose 部署指南》完成一次成功部署（curl /api/status 返回 {"message":"Ok",...}）；
2. 能编辑部署目录下的 .env 并重建服务；
3. 理解两条基本原则：Infisical 的配置面几乎全部收敛在 .env 一处；改完必须重建服务才生效（不是简单 restart，见第三节实测）。

三、参数查看与修改方式

3.1 查看当前生效参数

方式一：进入主服务打印进程环境（实测）：

cd /opt/infisical
docker compose exec backend env | grep -E '^(ENCRYPTION_KEY|AUTH_SECRET|SITE_URL|DB_CONNECTION_URI|REDIS_URL|NODE_ENV|SMTP_HOST|SMTP_PORT|SMTP_IGNORE_TLS|POSTGRES_USER)' | sort

实测输出：

AUTH_SECRET=Qnpybz93CwO9HwntKVj7NpCTK+xGQa+s4U9fxG5j8mU=
DB_CONNECTION_URI=postgres://infisical:infisical@db:5432/infisical
ENCRYPTION_KEY=6acfada71d5fd5854aa12e8ca5f624ea
NODE_ENV=production
POSTGRES_USER=infisical
REDIS_URL=redis://redis:6379
SITE_URL=http://localhost:8128
SMTP_HOST=smtp-sink
SMTP_IGNORE_TLS=true
SMTP_PORT=1025

方式二：健康接口核对关键开关（实测）：

curl -s http://localhost:8128/api/status

{"date":"2026-10-21T10:17:35.730Z","message":"Ok","emailConfigured":true,"inviteOnlySignup":true,"redisConfigured":true,"secretScanningConfigured":false,"auditLogStorageDisabled":false,"maxIdentityAccessTokenTTL":7776000}

字段解读：emailConfigured 反映 SMTP 组是否完整；redisConfigured 反映 Redis 连接；secretScanningConfigured 反映 GitHub Radar 类扫描集成；auditLogStorageDisabled 反映审计日志存储开关。

方式三：确认监听地址与端口（实测，/proc/net/tcp 中 1F90 即 8080）：

docker compose exec backend env | grep -E '^HOST='
docker compose exec backend cat /proc/net/tcp | head -3

HOST=0.0.0.0
   0: 0B00007F:8B89 00000000:0000 0A ...
   1: 00000000:1F90 00000000:0000 0A ...

00000000:1F90 表示 0.0.0.0:8080 全接口监听（官方镜像已内置 HOST=0.0.0.0，Compose 映射端口即可对外提供服务）。

3.2 修改参数与生效方式

以关闭遥测上报与版本检查为例，实测完整闭环：

# 1. 追加配置
cat >> /opt/infisical/.env <<'EOF'

# 遥测上报开关
TELEMETRY_ENABLED=false
DISABLE_UPDATE_CHECK=true
EOF

# 2. 重建主服务（配置经 env_file 注入，必须重建而非 restart）
docker compose up -d backend

# 3. 验证参数已进入进程环境
docker compose exec backend env | grep -E '^(TELEMETRY_ENABLED|DISABLE_UPDATE_CHECK)'

实测输出：

 Container infisical-backend Started
TELEMETRY_ENABLED=false
DISABLE_UPDATE_CHECK=true

再核对服务健康未受影响（实测）：

curl -s http://localhost:8128/api/status | head -c 120

{"date":"2026-10-21T10:33:05.926Z","message":"Ok","emailConfigured":true,"redisConfigured":true,

💡 说明：docker compose restart backend 只重启进程，不会重新读取 .env 中新增的变量组合所对应的容器环境（容器环境在创建时注入）；凡涉及环境变量增删，统一用 docker compose up -d backend 重建，这是本方案唯一的生效方式。

3.3 参数来源与优先级

参数注入链路为：.env 文件 →（compose 的 env_file:）→ 容器环境变量 → 应用配置模块。优先级从高到低：

1. compose 文件中 environment: 段的显式键值（如 NODE_ENV=production），会覆盖 .env 同名值；
2. .env 文件；
3. 官方镜像内置默认值（如 HOST=0.0.0.0）与代码内默认值（如 PORT 默认 8080）。

最小必填四件套【实查官方文档】：ENCRYPTION_KEY、AUTH_SECRET、DB_CONNECTION_URI、REDIS_URL——缺任一项实例无法启动。

四、参数总览

按官方文档分类给出总表，便于按域检索：

五、核心参数分类详解

5.1 通用平台参数

ENCRYPTION_KEY（必填）【实查+实测】

• 含义：应用层加密根密钥（KMS ROOT Key），机密密文、项目密钥派生都依赖它；
• 格式：随机 16 字节十六进制串，openssl rand -hex 16 生成；FIPS 部署改为 256 位 base64（openssl rand -base64 32）；
• 实测行为：首次启动日志可见 KMS: Generating new ROOT Key with software encryption，随后反复出现 KMS: Loading ROOT Key into Memory.；
• ⚠️ 生成后不可随手更换：换新钥后存量机密全部无法解密，密钥轮换必须走官方流程。生产另将 KMS 根密钥托管到 HSM/云 KMS 的高阶用法见 HSM_LIB_PATH、HSM_SLOT、HSM_PIN、HSM_KEY_LABEL 一组参数【实查镜像配置模块】。

AUTH_SECRET（必填）【实查+实测】

• 含义：JWT 签名密钥，用户登录态与令牌签名；
• 格式：随机 32 字节 base64，openssl rand -base64 32 生成；
• 实测行为：登录、注册返回的 token 均由其签名；更换后所有已登录会话失效（重新登录即可，无数据风险）。

SITE_URL（必填）【实查+实测】

• 含义：对外访问地址（含协议的绝对 URL）；
• 实测行为：本文实验值为 http://localhost:8128；注册验证邮件中的链接、SSO 回调都基于它拼接。反代 HTTPS 场景必须改成对外域名，否则邮件链接与 Cookie 安全标记异常。

PORT / HOST【实查+实测】

• PORT：应用内部监听端口，默认 8080（实测 /proc/net/tcp 见 0.0.0.0:1F90，1F90=8080）；
• HOST：监听网卡，文档默认 localhost，但官方镜像环境已内置 HOST=0.0.0.0【实测】，Compose 部署无需显式设置；裸机直装进程时才需要显式 HOST=0.0.0.0。

TELEMETRY_ENABLED / DISABLE_UPDATE_CHECK【实测】

• TELEMETRY_ENABLED 默认 true，置 false 关闭匿名遥测（本文 3.2 节实测生效）；
• DISABLE_UPDATE_CHECK 默认 false：实例每周（及启动时）向 GitHub 查一次新版本并在 UI 提示；置 true 完全不发该请求，离线内网部署建议开启。

TRUSTED_PROXY_CIDRS【实查】

• 含义：可信反代网段列表（逗号分隔 CIDR 或 loopback/linklocal/uniquelocal 别名）；
• 行为：设置后仅可信代理发来的 X-Forwarded-For 被采信，防止 IP 白名单被伪造头绕过；未设置时沿用旧行为（信任所有转发头）。置于 NGINX/ALB/Cloudflare 之后必须配置。

ALLOW_INTERNAL_IP_CONNECTIONS / DYNAMIC_SECRET_ALLOW_INTERNAL_IP / AUDIT_LOG_STREAM_ALLOW_INTERNAL_IP【实查】

• 含义：SSRF 防护放宽开关，默认均 false。允许 App Connections/动态密钥/审计流直连内网 IP；
• 官方建议优先用 Gateway 隧道访问私网资源，仅在确有直连需求时按域开窄开关（全局开关同时禁用 DNS-rebinding 防护，暴露面更大）。

5.2 CORS 参数

CORS_ALLOWED_ORIGINS【实查】

• 默认取 SITE_URL 同值；JSON 数组格式：CORS_ALLOWED_ORIGINS=["https://console.example.com"]；
• 场景：前端控制台与 API 不同域时显式放行。

CORS_ALLOWED_METHODS【实查】

• 默认反射请求的 Access-Control-Request-Headers；一般无需改动。

5.3 数据层参数（PostgreSQL）

DB_CONNECTION_URI（必填）【实测】

• 格式：postgres://<user>:<password>@<host>:5432/<db>；本文实测 postgres://infisical:infisical@db:5432/infisical（compose 内服务名 db）；
• 外接托管库（如 RDS）时改此串并从 compose 移除 db 服务；数据库账号需对库有建表/改表全部权限（启动迁移要 DDL 权限）。

DB_ROOT_CERT【实查】

• 托管库 TLS 场景使用：CA 证书 base64 编码后填入（cat rds-ca.pem | base64），连接串追加 ?sslmode=verify-ca。

DB_READ_REPLICAS【实查】

• 读副本连接串，JSON 数组：[{"DB_CONNECTION_URI":"postgres://..."}]，配套 DB_ROOT_CERT 每副本独立；
• 官方建议扩读用副本，而非盲目调大主池。

POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB【实测】

• 仅供 compose 内 db 服务初始化使用，与 DB_CONNECTION_URI 保持一致（官方模板即此设计）。

5.4 连接池参数

全部默认值适用于小规模部署【实查】：

容量核算公式【实查官方文档】：每实例峰值 = DB_POOL_MAX + DB_REPLICA_POOL_MAX × 副本数 + AUDIT_LOGS_DB_POOL_MAX（如启用审计库），总峰值 = 每实例峰值 × 实例数。注意滚动发布期间瞬时翻倍、自动扩容按最大副本数算；贴近数据库 max_connections 时应下调 DB_POOL_MAX 而非调大 max_connections。

5.5 审计日志参数

实测印证：未配置 ClickHouse 时启动日志提示 No ClickHouse client configured: Skipping ClickHouse audit_logs table creation.，/api/status 中 auditLogStorageDisabled:false【实测】。

5.6 Redis 参数

REDIS_URL（必填）【实测】

• 格式：redis://[:password@]host:6379，TLS 用 rediss://（双 s）；本文实测 redis://redis:6379；
• 行为：缺省时实例拒绝启动——Redis 是缓存与任务队列（BullMQ）的硬依赖。

REDIS_SENTINEL_HOSTS / REDIS_CLUSTER_HOSTS【实查】

• 三选一必填：单机 URL、Sentinel 主机组、Cluster 主机组；
• 官方明确：Redis 推荐 active-passive 形态，未在 active-active 上验证过。

5.7 SMTP 邮件参数

注册验证码、组织邀请、密码重置全部走邮件，是自托管首日必需项：

实测排障（完整过程见《Infisical v0.166.9 Docker Compose 部署指南》4.4 节）：默认 TLS 握手对内网明文 SMTP 报 SSL routines:tls_validate_record_header:wrong version number，补 SMTP_IGNORE_TLS=true 后 /api/status 的 emailConfigured 由 false 变 true，注册验证码正常送达【实测】。

5.8 认证与机器身份参数

• COOKIE_SECRET_SIGN_KEY【实查】：OAuth SSO/SAML/OIDC/LDAP 登录流会话 Cookie 签名键，默认从 KMS 根密钥派生（多副本自动一致）；自行管理时设 32 字节 base64，更换会使进行中的登录全部失效；
• SSO 组【实查】：CLIENT_ID_GOOGLE_LOGIN、CLIENT_ID_GITHUB_LOGIN、CLIENT_ID_GITLAB_LOGIN（及对应 SECRET）、CLIENT_ID_GITHUB_APP 等按需启用；
• 机器身份认证【实查】：INFISICAL_UNIVERSAL_AUTH_...（Universal Auth client/secret 校验）、Kubernetes/GCP/Azure/AWS/OIDC/LDAP 各认证模板对应一组参数，CLI 与 CI 拉取机密走机器身份而非用户登录；
• 密码策略【实测】：默认策略硬编码最少 14 位、至少含字母与数字/特殊字符、不得出现 4 个以上连续重复字符（实测 8 位密码注册被拒），自托管当前无环境变量可放宽。

5.9 可观测参数

• OTEL_TELEMETRY_COLLECTION_ENABLED=true + OTEL_EXPORT_TYPE=prometheus【实查】：开启 Prometheus 指标暴露（9464 端口），配合 compose 增加端口映射后由 Prometheus 抓取；
• LOG_LEVEL：应用日志级别【实查镜像配置模块】；启动日志本身为 JSON 结构化行（含 severity/reqId），可直接对接日志采集。

六、生产配置模板

按部署规模给两档可直接套用的 .env 模板（密钥值自行生成）：

小规模（≤50 人团队，8 GB 内存 / 4 核 / 50 GB SSD，单实例 + 本机 PostgreSQL/Redis）：

ENCRYPTION_KEY=<openssl rand -hex 16>
AUTH_SECRET=<openssl rand -base64 32>
NODE_ENV=production
POSTGRES_USER=infisical
POSTGRES_PASSWORD=<强口令>
POSTGRES_DB=infisical
DB_CONNECTION_URI=postgres://infisical:<强口令>@db:5432/infisical
REDIS_URL=redis://redis:6379
SITE_URL=https://secrets.example.com
HTTPS_ENABLED=true
TELEMETRY_ENABLED=false
DISABLE_UPDATE_CHECK=true
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_REQUIRE_TLS=true
SMTP_FROM_ADDRESS=noreply@example.com
SMTP_FROM_NAME=Infisical
SMTP_USERNAME=<SMTP账号>
SMTP_PASSWORD=<SMTP口令>

中规模（百人级、多实例 + 托管 PostgreSQL/Redis，16 GB+ 内存）：

ENCRYPTION_KEY=<openssl rand -hex 16>
AUTH_SECRET=<openssl rand -base64 32>
NODE_ENV=production
DB_CONNECTION_URI=postgres://infisical:<强口令>@pg-master.internal:5432/infisical?sslmode=verify-ca
DB_ROOT_CERT=<托管库CA base64>
DB_READ_REPLICAS=[{"DB_CONNECTION_URI":"postgres://infisical:<强口令>@pg-replica.internal:5432/infisical?sslmode=verify-ca"}]
DB_POOL_MAX=20
REDIS_URL=redis://:<密码>@redis.internal:6379
SITE_URL=https://secrets.example.com
HTTPS_ENABLED=true
TRUSTED_PROXY_CIDRS=10.0.0.0/8
TELEMETRY_ENABLED=false
DISABLE_UPDATE_CHECK=true
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_REQUIRE_TLS=true
SMTP_FROM_ADDRESS=noreply@example.com
SMTP_FROM_NAME=Infisical
SMTP_USERNAME=<SMTP账号>
SMTP_PASSWORD=<SMTP口令>

关键差异：中规模把数据库/Redis 外移托管、开读副本与 TLS、按容量公式上调 DB_POOL_MAX、加 TRUSTED_PROXY_CIDRS 收紧转发头信任。

七、常见问题（FAQ）

Q1：改了 .env 不生效？ docker compose restart 不会重读新增环境变量，必须 docker compose up -d backend 重建容器环境（3.2 节实测闭环）。

Q2：换了 ENCRYPTION_KEY 后机密读不出来？ 预期行为：根密钥只对加密它的那份数据有效。改回原值即可恢复；确需轮换走官方密钥轮换流程。

Q3：注册收不到验证码？ 先看 /api/status 的 emailConfigured；为 false 时排查 SMTP 组参数，内网明文 SMTP 别忘 SMTP_IGNORE_TLS=true；再查验证码 60 秒冷却限制。

Q4：离线内网部署对外请求有哪些？ 版本检查（GitHub）与遥测——分别用 DISABLE_UPDATE_CHECK=true、TELEMETRY_ENABLED=false 关闭【实查官方文档】。

Q5：多实例部署要注意什么？ 三件事：全部实例共享同一 ENCRYPTION_KEY/AUTH_SECRET；按连接池公式核算数据库总连接数；Redis 用 active-passive 而非 active-active【实查】。

Q6：审计日志想单独存、想外发怎么配？ 独立 PostgreSQL 用 AUDIT_LOGS_DB_CONNECTION_URI；高吞吐用 CLICKHOUSE_URL；外发到第三方日志平台用审计流（保持 AUDIT_LOG_STREAMS_ENABLED=true）。

八、参考链接

• 官方环境变量文档：https://infisical.com/docs/self-hosting/configuration/envars
• 官方编排模板与 .env.example：https://github.com/Infisical/infisical/blob/main/.env.example
• 审计日志 ClickHouse 指南：https://infisical.com/docs/documentation/platform/audit-logs-clickhouse-setup
• 站内延伸：《Infisical 介绍与选型指南》、《Infisical v0.166.9 Docker Compose 部署指南》、《Infisical v0.166.9 常用 CLI 命令与工具详解》