Infisical v0.166.9 Docker Compose 部署指南
Infisical v0.166.9 官方 Compose 三服务（主服务 + PostgreSQL 14 + Redis 7）从零部署实测：版本钉选、SMTP 明文通道与 TLS 排障、v3 邮箱验证码注册管理员、数据持久化备份恢复与升级运维，回显逐条实测。
Infisical v0.166.9 Docker Compose 部署指南
目标：在一台 Ubuntu 22.04 服务器上，用官方 Docker Compose 方案从零部署 Infisical v0.166.9 密钥管理平台（主服务 + PostgreSQL 14 + Redis 7），完成 SMTP 配置、首个管理员注册、健康验证与数据持久化，全部步骤与回显已在实际部署环境逐条实测通过（2026-10-21）。
一、环境信息
- 操作系统：Ubuntu 22.04 LTS（x86_64）
- Infisical：v0.166.9（2026-10-21 GitHub Releases 最新稳定标签）
- 数据库：PostgreSQL 14（官方模板镜像 postgres:14-alpine）
- 缓存/队列：Redis 7（redis:7-alpine）
- Docker：Docker Engine 20.10+ 与 Docker Compose v2（部署前实测
docker compose version为 v2.x） - 端口：主服务容器内监听 8080，宿主机映射 8128（本文实测环境的宿主机 80 端口已被既有服务占用，故改用 8128；无冲突时可按官方默认
80:8080，本文所有回显以 8128 为准） - 部署目录：
/opt/infisical/（编排文件与 .env 所在），数据目录/opt/infisical/data/postgres、/opt/infisical/data/redis - 版本取证：GitHub Releases
https://github.com/Infisical/infisical/releases/latest（2026-10-21 实查）
二、镜像选型说明
官方 docker-compose.prod.yml 模板包含三个服务，版本选择建议如下：
| 服务 | 官方模板镜像 | 本文采用 | 说明 |
|---|---|---|---|
| 主服务 | infisical/infisical:latest（模板注明需自行钉版本） | infisical/infisical:v0.166.9 | 官方模板将 latest 标注「PIN THIS TO A SPECIFIC TAG」，生产必须钉死具体版本 |
| 数据库 | postgres:14-alpine | postgres:14-alpine | 与官方模板一致；如用更高版本 PostgreSQL，先核对官方升级说明 |
| 缓存 | redis（未钉版本） | redis:7-alpine | 钉到 7 系列避免 8.x 行为差异 |
关键差异：官方模板的 latest 镜像与未钉版本的 redis 适合快速试玩；生产部署三处都应钉版本，且升级前先备份数据库（本文第七节给出实测命令）。Infisical 主服务镜像约 2.8 GB（解压后 627 MB 可见层），首次拉取需要预留带宽。
三、前置条件
- 服务器已安装 Docker Engine 20.10+ 与 Docker Compose v2，验证命令与实测回显：
docker --version
docker compose version
实测输出（本机）：
Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1
- 服务器可访问外网（拉取镜像）或已配置镜像加速/代理；
- 至少 4 GB 可用内存、20 GB 磁盘（官方最低要求 2 核/4 GB/20 GB，推荐 4 核/8 GB/50 GB+ SSD）；
- 准备一个邮件通道用于注册验证码：注册流程强制邮箱验证（见 4.4 节），生产环境配置企业 SMTP；本文实测用内网 SMTP 收信服务代替，便于取回验证码；
- 防火墙仅放行主服务端口（80/443 或自定义端口），PostgreSQL 5432 与 Redis 6379 不得对公网暴露。
四、部署步骤
4.1 建目录与下载官方模板
本节创建部署目录并取回官方编排模板与默认凭据文件。官方文档给的是 main 分支原始文件，作为模板参考；本文随后钉版本并落数据目录。
mkdir -p /opt/infisical/data/postgres /opt/infisical/data/redis /opt/infisical/logs
cd /opt/infisical
curl -o docker-compose.official.yml https://raw.githubusercontent.com/Infisical/infisical/main/docker-compose.prod.yml
curl -o .env.example https://raw.githubusercontent.com/Infisical/infisical/main/.env.example
chmod 600 .env.example
⚠️ 官方
.env.example内置的ENCRYPTION_KEY与AUTH_SECRET是公开示例值，仅可用于试玩；生产必须重新生成（见第六节），否则任何人都能用它解密你的机密。
4.2 编写 docker-compose.yml
本节在官方模板基础上做三处生产化调整：钉版本、bind mount 数据目录、显式项目名。在 /opt/infisical/docker-compose.yml 写入：
name: infisical-v0.166.9-stack
services:
backend:
container_name: infisical-backend
restart: unless-stopped
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
image: infisical/infisical:v0.166.9
env_file: .env
ports:
- "8128:8080" # 官方默认 80:8080；宿主机 80 被占用时改用其他端口
environment:
- NODE_ENV=production
networks:
- infisical-net
volumes:
- /opt/infisical/logs:/app/logs
redis:
image: redis:7-alpine
container_name: infisical-redis
env_file: .env
restart: always
environment:
- ALLOW_EMPTY_PASSWORD=yes
networks:
- infisical-net
volumes:
- /opt/infisical/data/redis:/data
db:
container_name: infisical-postgres
image: postgres:14-alpine
restart: always
env_file: .env
volumes:
- /opt/infisical/data/postgres:/var/lib/postgresql/data
networks:
- infisical-net
healthcheck:
test: "pg_isready --username=${POSTGRES_USER} && psql --username=${POSTGRES_USER} --list"
interval: 5s
timeout: 10s
retries: 10
networks:
infisical-net:
driver: bridge
逐项说明：
name:固定编排项目名，避免多套部署同名项目互相干扰；depends_on的service_healthy保证数据库健康检查通过后主服务才启动，避免首启竞态；container_name便于日志排查与docker logs直达；- 三个
volumes均用 bind mount，数据落盘位置一目了然，方便备份与迁移； - 未显式声明
ipam子网时由 Docker 自动分配；如需固定网段，可加ipam.config.subnet（先确认该网段未被既有网络占用）。
4.3 编写 .env 并启动
本节写入最小可用配置。生产环境先重新生成两个密钥：
# 生成 32 位十六进制加密根密钥
openssl rand -hex 16
# 生成 JWT 签名密钥（base64）
openssl rand -base64 32
实测输出：
6acfada71d5fd5854aa12e8ca5f624ea
Qnpybz93CwO9HwntKVj7NpCTK+xGQa+s4U9fxG5j8mU=
在 /opt/infisical/.env 写入（值替换为你生成的）：
# 应用层加密根密钥（必填，丢失将无法解密存量机密）
ENCRYPTION_KEY=6acfada71d5fd5854aa12e8ca5f624ea
# JWT 签名密钥（必填）
AUTH_SECRET=Qnpybz93CwO9HwntKVj7NpCTK+xGQa+s4U9fxG5j8mU=
# PostgreSQL 凭据
POSTGRES_PASSWORD=infisical
POSTGRES_USER=infisical
POSTGRES_DB=infisical
# 数据库与 Redis 连接（compose 内部服务名 db / redis）
DB_CONNECTION_URI=postgres://infisical:infisical@db:5432/infisical
REDIS_URL=redis://redis:6379
# 对外访问地址（反代/HTTPS 场景改为对外域名）
SITE_URL=http://localhost:8128
# SMTP：注册验证码、邀请与密码重置邮件（注册流程必需）
SMTP_HOST=smtp.example.internal
SMTP_PORT=1025
SMTP_IGNORE_TLS=true
SMTP_REQUIRE_TLS=false
SMTP_FROM_ADDRESS=noreply@example.com
SMTP_FROM_NAME=Infisical
SMTP_USERNAME=
SMTP_PASSWORD=
⚠️ SMTP 默认尝试 TLS 握手。对内网明文 SMTP 服务必须加
SMTP_IGNORE_TLS=true与SMTP_REQUIRE_TLS=false，否则注册请求报wrong version number（实测排障见 4.4 节）。
启动并观察状态：
cd /opt/infisical
docker compose up -d
docker compose ps
实测输出：
Container infisical-backend Starting
Container infisical-backend Started
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
infisical-backend infisical/infisical:v0.166.9 "docker-entrypoint.s…" backend 37 seconds ago Up 32 seconds 443/tcp, 0.0.0.0:8128->8080/tcp
infisical-postgres postgres:14-alpine "docker-entrypoint.s…" db 38 seconds ago Up 37 seconds (healthy) 5432/tcp
infisical-redis redis:7-alpine "docker-entrypoint.s…" redis 38 seconds ago Up 37 seconds 6379/tcp
💡 说明：
db显示healthy说明健康检查通过；backend 的 443/tcp 是镜像内部声明的备用端口，未映射即可忽略。
4.4 注册首个管理员（含两处实测排障）
本节完成首个管理员注册。第一个注册的用户自动成为实例管理员。注册走邮箱验证码流程（v3 API：/api/v3/signup/email/signup → email/verify → complete-account），浏览器访问 http://<服务器IP>:8128 按界面操作即可；下文用 API 方式实录全过程，便于无人值守环境照做。
第一步：确认服务就绪与健康状态（实测回显）：
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}
关键字段解读：message:"Ok" 服务正常；emailConfigured:true 表示 SMTP 已正确加载——若为 false，注册会失败；redisConfigured:true 表示 Redis 就绪。
第二步：发起注册，获取验证码：
curl -s -X POST http://localhost:8128/api/v3/signup/email/signup \
-H 'Content-Type: application/json' \
-d '{"email":"admin@example.com"}'
{"message":"Sent an email verification code to admin@example.com","cooldownSeconds":60}
到收件箱取 6 位验证码（邮件主题为 Infisical confirmation code: 6位数字）。验证码 60 秒内有冷却限制，同邮箱连续重试需等待。
第三步：验证邮箱并完成账号创建（两步都必须带 User-Agent 头）：
# 验证邮箱，返回 signupToken
curl -s -X POST http://localhost:8128/api/v3/signup/email/verify \
-H 'Content-Type: application/json' \
-d '{"email":"admin@example.com","code":"274641"}'
{"message":"Successfully verified email","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoVG9rZW5UeXBlIjoic2lnbnVwVG9rZW4iLCJ1c2VySWQiOiI1Yjg5NTQ2Yi1jM2E3LTQxODItYjRjNi1lMmZjMTg3YjAyYzgiLCJpYXQiOjE3OTI1Nzc5NjUsImV4cCI6MTc5MjU3ODg2NX0.zSWy0QMksP3XWPrvvNAck1xt47apNfKWhuO9tJSVwRI","user":{"username":"admin@example.com","email":"admin@example.com","isEmailVerified":true,"firstName":null,"lastName":null,"id":"5b89546b-c3a7-4182-b4c6-e2fc187b02c8"}}
输出说明：
token字段即 signupToken（JWT 完整回显），下一步建号时置于Authorization: Bearer头。
# 用 signupToken 完成建号（密码需满足默认策略：至少 14 位）
curl -s -X POST http://localhost:8128/api/v3/signup/complete-account \
-H 'Content-Type: application/json' \
-H 'User-Agent: curl/8.5.0' \
-H "Authorization: Bearer <上一步返回的token>" \
-d '{"type":"email","email":"admin@example.com","firstName":"admin","lastName":"ops","password":"q1w2e3r4q1w2e3r4","organizationName":"Demo Organization"}'
{"message":"Successfully set up account","user":{"username":"admin@example.com","email":"admin@example.com","isEmailVerified":true,"firstName":"admin","lastName":"ops","authMethods":["email"],"id":"5b89546b-c3a7-4182-b4c6-e2fc187b02c8"},"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoTWV0aG9kIjoiZW1haWwiLCJhdXRoVG9rZW5UeXBlIjoiYWNjZXNzVG9rZW4iLCJ1c2VySWQiOiI1Yjg5NTQ2Yi1jM2E3LTQxODItYjRjNi1lMmZjMTg3YjAyYzgiLCJ0b2tlblZlcnNpb25JZCI6ImU5Y2Y1YWJmLWQ4MWUtNDU0Ny1iNzVhLTA3ZjljZTRkODVmYiIsImFjY2Vzc1ZlcnNpb24iOjEsIm9yZ2FuaXphdGlvbklkIjoiZTZhMWJiNzEtYjc2NS00ZGNmLWI1ZjEtOTRlYjllMGFlODRiIiwiaWF0IjoxNzkyNTc4MDQ5LCJleHAiOjE3OTM0NDIwNDl9.kROC-T1alI588eKyebsDDmIR5JoXg_DgH2eNQ6xcYzM"}
返回 Successfully set up account 即注册完成，用该账号登录 http://<服务器IP>:8128 进入控制台。
⚠️ 排障实录一：默认密码策略强制 14 位以上。实测用 8 位密码
q1w2e3r4会被策略拒绝（密码校验定义^[\s\S]{14,}$，且至少含字母、数字或特殊字符，不得出现 4 个以上连续重复字符），本文演示口令在其基础上重复一次凑足 16 位。⚠️ 排障实录二：SMTP 明文通道注册报 500。未加
SMTP_IGNORE_TLS=true时，实测报错如下：SMTP - Failed to connect to smtp-sink:1025 - error:0A00010B:SSL routines:tls_validate_record_header:wrong version number原因：SMTP 客户端默认对连接做 TLS 握手，而内网明文 SMTP 服务不支持。解决：
.env增加SMTP_IGNORE_TLS=true、SMTP_REQUIRE_TLS=false后docker compose up -d backend重建生效（/api/status的emailConfigured随之变 true）。⚠️ 排障实录三：老版本注册接口已废弃。v0.166.x 已移除
/api/v1/auth/signup与/api/v2/signup，实测均返回404 Route POST:/api/v1/auth/signup not found；现行为/api/v3/signup/email/signup（发码）→/api/v3/signup/email/verify（验码）→/api/v3/signup/complete-account（建号）三段式，且验证码一次性有效，重放会失败。
第四步：确认后端启动日志（首次启动含数据库迁移与 KMS 初始化，实测节选）：
{"severity":"INFO","msg":"Running Infisical vv0.166.9"}
{"severity":"INFO","msg":"Migration tables initialized"}
{"severity":"INFO","msg":"Running application migrations."}
{"severity":"INFO","msg":"KMS: Generating new ROOT Key with software encryption"}
{"severity":"INFO","msg":"KMS: Loading ROOT Key into Memory."}
{"severity":"INFO","msg":"Folder commits initialized"}
Running Infisical vv0.166.9 确认运行版本；迁移在启动时自动执行，看到服务 Up 且 /api/status 正常即迁移成功。
五、数据持久化说明
本节说明数据落盘位置与备份恢复命令。三个服务的持久化关系：
| 数据 | 宿主机路径 | 内容 | 丢失影响 |
|---|---|---|---|
| PostgreSQL | /opt/infisical/data/postgres | 全部加密机密、用户、项目、审计元数据 | 不可恢复，等同于丢全部数据 |
| Redis | /opt/infisical/data/redis | 缓存与任务队列 | 可再生，影响轻微 |
| 应用日志 | /opt/infisical/logs | 运行日志 | 仅影响排查 |
备份（逻辑导出）：
cd /opt/infisical
docker compose exec db pg_dump -U infisical infisical > backup_$(date +%Y%m%d_%H%M%S).sql
恢复：
cd /opt/infisical
docker compose exec -T db psql -U infisical infisical < backup_20261021_183000.sql
⚠️ 仅恢复数据库不够：
ENCRYPTION_KEY是应用层加密根密钥，必须与备份时一致，否则恢复后机密无法解密。.env应与数据库备份一起纳入备份策略。
六、环境变量表
Infisical 的配置面几乎全部收敛在 .env，主服务与 PostgreSQL/Redis 共用该文件。核心变量如下（完整清单见官方文档 infisical.com/docs/self-hosting/configuration/envars）：
| 变量 | 必填 | 默认/示例 | 说明 |
|---|---|---|---|
ENCRYPTION_KEY | 是 | 32 位 hex | 应用层加密根密钥，openssl rand -hex 16 生成；更换后存量机密不可解密 |
AUTH_SECRET | 是 | base64 串 | JWT 签名密钥，openssl rand -base64 32 生成 |
NODE_ENV | 是 | production | 生产模式开关，由 compose 的 environment 注入 |
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB | 是 | infisical | 数据库初始化凭据，compose 的 db 服务与主服务共用 |
DB_CONNECTION_URI | 是 | postgres://user:pass@db:5432/db | 数据库连接串；外接托管数据库时改此处并移除 db 服务 |
REDIS_URL | 是 | redis://redis:6379 | Redis 连接串；外接托管 Redis 时改此处 |
SITE_URL | 是 | http://localhost:8128 | 对外访问地址，影响邮件里的链接与 Cookie 行为；HTTPS 部署改为 https://域名 |
SMTP_HOST / SMTP_PORT | 注册必需 | — | SMTP 服务器地址与端口 |
SMTP_IGNORE_TLS | 视情况 | false | true = 不发起 TLS（明文内网 SMTP 必开） |
SMTP_REQUIRE_TLS | 视情况 | false | true = 强制 STARTTLS 升级 |
SMTP_FROM_ADDRESS / SMTP_FROM_NAME | 注册必需 | — | 发件人与显示名 |
SMTP_USERNAME / SMTP_PASSWORD | 视情况 | — | SMTP 认证凭据 |
SMTP_TLS_REJECT_UNAUTHORIZED | 视情况 | true | 自签证书的内网 SMTP 需置 false |
SMTP_HELO_HOST | 可选 | — | 自定义 HELO 主机名 |
HTTPS_ENABLED | 可选 | false | 反代终结 TLS 时置 true，影响安全 Cookie 标记 |
七、配置参数说明
本节给出三个最值得改的参数域与改法：
- 加密与签名密钥：
ENCRYPTION_KEY与AUTH_SECRET是整个平台的安全根基。改动流程：改.env→docker compose up -d backend重建 → 用/api/status验证服务恢复。ENCRYPTION_KEY一旦有存量机密就不可随意更换（需走官方密钥轮换流程）。 - 端口与对外地址：宿主端口改
ports映射左侧；SITE_URL必须与实际访问地址一致，否则邮件中的链接打不开、登录 Cookie 行为异常。两者改完统一docker compose up -d重建。 - 外接数据库/Redis：托管数据库场景把
DB_CONNECTION_URI、REDIS_URL指向外部地址，并从 compose 中删除db、redis两个服务定义；主服务的depends_on同步删除。改完docker compose up -d重建验证。
八、配置文件挂载
本方案所有配置经 env_file: .env 注入，无需挂载应用配置文件。需要扩展挂载时的规范位置：
- SMTP 自定义 CA 证书：将证书文件放宿主机目录并挂载，配合
SMTP_CUSTOM_CA_CERT指向容器内路径； - 应用日志目录：
/opt/infisical/logs:/app/logs（本方案已挂载）； .env文件权限收紧：chmod 600 /opt/infisical/.env，其中含两把根密钥与数据库口令。
九、等价 docker run
不用 Compose 时，与上述部署等价的最小手工命令（同一自定义网络内依次执行；实际部署仍建议用 Compose 管理生命周期）：
# 1. 创建网络
docker network create infisical-net
# 2. PostgreSQL
docker run -d --name infisical-postgres --network infisical-net --restart always \
-e POSTGRES_USER=infisical -e POSTGRES_PASSWORD=infisical -e POSTGRES_DB=infisical \
-v /opt/infisical/data/postgres:/var/lib/postgresql/data \
postgres:14-alpine
# 3. Redis
docker run -d --name infisical-redis --network infisical-net --restart always \
-v /opt/infisical/data/redis:/data \
redis:7-alpine
# 4. 主服务
docker run -d --name infisical-backend --network infisical-net --restart unless-stopped \
--env-file /opt/infisical/.env \
-e NODE_ENV=production \
-p 8128:8080 \
-v /opt/infisical/logs:/app/logs \
infisical/infisical:v0.166.9
十、常用运维命令
本节收录日常运维高频命令（均在实测环境验证过语法与行为）：
cd /opt/infisical
# 服务状态
docker compose ps
# 查看主服务日志（跟踪模式 / 最近 100 行）
docker compose logs -f backend
docker compose logs --tail=100 backend
# 单服务重启（改完 .env 后对 backend 生效）
docker compose restart backend
# 或配置项涉及镜像/环境注入时用重建
docker compose up -d backend
# 停止与再启动
docker compose down
docker compose up -d
# 升级版本：改 docker-compose.yml 中镜像 tag 后执行
docker compose pull
docker compose up -d
docker compose logs -f backend # 观察自动迁移日志
数据库连通性自检：
docker compose exec db pg_isready -U infisical
docker compose exec db psql -U infisical -c "SELECT 1"
实测输出：
/var/run/postgresql:5432 - accepting connections
?column?
----------
1
(1 row)
十一、常见问题（FAQ）
Q1：docker compose up 时报端口被占用？
宿主机 80（或自定义端口）被既有服务占用。改 ports 左侧为空闲端口即可；用 ss -ltn | grep :<端口> 先确认空闲。本文实测即因 80/8080 被占用而映射到 8128。
Q2：backend 反复重启，日志报数据库连接失败？
多数是 DB_CONNECTION_URI 与 POSTGRES_USER/PASSWORD/DB 不一致，或 db 服务未就绪。先 docker compose ps 确认 db 状态为 healthy，再 docker compose exec db pg_isready -U infisical 验证；若凭据不一致，修正 .env 后重建。
Q3：注册时邮箱验证码收不到？
依次检查：/api/status 的 emailConfigured 是否为 true；backend 日志有无 SMTP 握手错误；内网明文 SMTP 是否漏配 SMTP_IGNORE_TLS=true（见 4.4 排障实录二）；验证码有 60 秒冷却，连发需等待。
Q4：注册接口 404？
v0.166.x 已移除 /api/v1/auth/signup 等旧路由，改用 v3 三段式（见 4.4 节），或直接用浏览器在控制台注册。
Q5：注册密码被拒？ 默认策略最少 14 位，且至少含字母、数字或特殊字符，不得出现 4 个以上连续重复字符。
Q6：忘记管理员密码？
访问登录页的找回密码入口走邮件重置（依赖 SMTP 正常）；SMTP 不可用时只能从备份恢复或重建实例，因此 .env 中 SMTP 配置在生产不可省略。
Q7：升级后起不来？
先 docker compose logs backend 看迁移报错；Infisical 迁移在启动时自动执行，跨大版本前应查官方 upgrade.infisical.com 的迁移影响说明，并先完成第七节的数据库备份。
十二、卸载与清理
cd /opt/infisical
docker compose down # 停止并移除三个服务与网络（保留 bind mount 数据）
docker compose down -v # 连同命名卷一并移除（本方案为 bind mount，数据仍在宿主机目录）
rm -rf /opt/infisical/data # 彻底清除数据（不可逆，先确认备份）
⚠️
down不会删除 bind mount 数据目录；确认不再使用后需手动删除/opt/infisical/data，删除前务必留有数据库备份与ENCRYPTION_KEY。
十三、参考链接
-
官方 Docker Compose 部署文档：https://infisical.com/docs/self-hosting/deployment-options/docker-compose
-
官方编排模板：https://github.com/Infisical/infisical/blob/main/docker-compose.prod.yml
-
自托管环境变量清单：https://infisical.com/docs/self-hosting/configuration/envars
-
升级指南：https://infisical.com/docs/self-hosting/guides/upgrading-infisical
-
站内延伸：《Infisical 介绍与选型指南》、《Infisical v0.166.9 配置参数详解》、《Infisical v0.166.9 常用 CLI 命令与工具详解》
-
本专栏系列：《Infisical v0.166.9 配置参数详解》。