Activepieces Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上用 Docker Compose 完成 Activepieces 0.92.3（社区版）的四组件部署（app + worker + PostgreSQL + Redis），掌握 AP_* 环境变量的逐项含义、密钥生成、数据持久化与版本升级的完整流程。本文全部命令与回显均在 Ubuntu 22.04 实测通过（实测日期：2026-10-18）。

一、环境信息

项目	值
宿主机	VMware 虚拟机
IP 地址	192.168.146.128
操作系统	Ubuntu 22.04 LTS
Docker	Docker Engine 28.x + Compose v2 插件
Activepieces 版本	0.92.3（社区版，GitHub 最新稳定版，2026-10-12 发布）
组件镜像	ghcr.io/activepieces/activepieces:0.92.3、pgvector/pgvector:0.8.0-pg14、redis:7.0.7
宿主端口	8100 → 容器 80（管理入口）
自定义网络	s3-activepieces_apnet（10.89.27.0/24）
出口网络	可直连 ghcr.io 与 npm registry；出口受限环境见第八章常见问题

部署完成后通过浏览器访问 http://192.168.146.128:8100 即可使用，服务端与执行器由同一官方镜像以不同环境变量拉起。

二、部署前检查

2.1 版本核实

动笔部署前先核实最新稳定版，避免拉到预发布版本：

curl -s -m 30 'https://api.github.com/repos/activepieces/activepieces/releases?per_page=5' | python3 -c "
import json,sys
for r in json.load(sys.stdin):
    print(r['tag_name'], '| prerelease:', r['prerelease'], '|', r['published_at'])
"

实测回显（查询日期 2026-10-18）：

0.92.3 | prerelease: False | 2026-10-12T18:43:34Z
0.92.2 | prerelease: False | 2026-10-07T09:27:59Z
0.92.1 | prerelease: False | 2026-09-30T11:51:23Z
0.92.0 | prerelease: False | 2026-09-24T18:49:44Z
0.91.3 | prerelease: False | 2026-09-24T21:04:30Z

prerelease: False 且发布时间最新的是 0.92.3，本文全文统一使用该版本。

2.2 宿主端口复核

原计划使用 8096 端口，先复核是否空闲：

for p in 8096 8099 8100 8101 8102 8103; do ss -ltn | grep -qE ":$p\b" && echo "$p USED" || echo "$p FREE"; done

实测回显（部署前）：

8099 USED
8100 FREE
8101 FREE
8102 FREE
8103 FREE

8096 已被服务器上其他服务占用，按顺延原则改用 8100 端口。后续所有访问地址均为 http://192.168.146.128:8100。

2.3 自定义网络复核与创建

创建部署专用的 bridge 网络前，先确认目标子网未被占用（禁用 192.168.0.0/16 与 100.64.0.0/16 网段，避免与业务网段及 CGNAT 冲突）：

docker network create -d bridge --subnet 10.89.27.0/24 s3-activepieces_apnet

实测回显：

0eb85f0a5a9b20b3bfa836b23f4d3354e660a44d63b62027d8f26e8084437fcb

创建后复核子网与宿主机路由完整性（确认新网络没有劫持默认路由）：

docker network inspect s3-activepieces_apnet --format '子网: {{range .IPAM.Config}}{{.Subnet}}{{end}} | 驱动: {{.Driver}}'
ip route get 192.168.1.62

实测回显：

子网: 10.89.27.0/24 | 驱动: bridge
192.168.1.62 via 192.168.146.2 dev ens33 src 192.168.146.128 uid 0
    cache

ip route get 显示去往外部网段的流量仍从 ens33 物理网卡走默认网关，新 bridge 网络不影响宿主机正常路由。

三、密钥生成与 .env 配置

3.1 生成系统级密钥

Activepieces 有三个必须自备的系统级密钥：连接器凭据加密密钥（32 位 hex，即 16 字节）、JWT 签名密钥、对外 API 密钥。统一用 openssl rand 生成并写入 .env 文件，避免明文写死在编排文件里：

echo "AP_API_KEY=$(openssl rand -hex 64)" | tee .env.key
echo "AP_ENCRYPTION_KEY=$(openssl rand -hex 16)" | tee .env.enc
echo "AP_JWT_SECRET=$(openssl rand -hex 32)" | tee .env.jwt
echo "AP_POSTGRES_PASSWORD=$(openssl rand -hex 32)" | tee .env.pg

实测回显（示例轮次，读者执行时会得到不同的随机值）：

AP_API_KEY=a7141499f302fb8e05af98fa3b534e37736219de75c153b2635b299283044b4fb6314770c5e67903b080e54ce2666adc45d4740626c811defdefdfdb76d721da
AP_ENCRYPTION_KEY=1bd0d9885d04efd7c10e64c71c10fb79
AP_JWT_SECRET=724d78205b127609ac1e9d94153140ad437bd5bd0447e7806fc332cb0902cd46
AP_POSTGRES_PASSWORD=ed57ea101a38683c4733ff9d1aefdbede007e3ac558548fc9f503beeda805d80

要点：

AP_ENCRYPTION_KEY 必须是 32 位十六进制字符串（16 字节），服务启动时会做严格校验（见第八章实录）；
这四个密钥一旦投入使用就不能随意更换：加密密钥换了会导致已保存的连接器凭据全部无法解密，JWT 密钥换了会导致所有登录会话失效；
请把 .env 纳入密钥管理（如 Vault），并确保它不会被提交到代码仓库。

3.2 编写 .env 文件

在部署目录写入 .env（Compose 会自动加载，供所有服务引用）：

cat > .env <<'EOF'
AP_ENGINE_EXECUTABLE_PATH=dist/packages/engine/main.js
AP_API_KEY=a7141499f302fb8e05af98fa3b534e37736219de75c153b2635b299283044b4fb6314770c5e67903b080e54ce2666adc45d4740626c811defdefdfdb76d721da
AP_ENCRYPTION_KEY=1bd0d9885d04efd7c10e64c71c10fb79
AP_JWT_SECRET=724d78205b127609ac1e9d94153140ad437bd5bd0447e7806fc332cb0902cd46
AP_ENVIRONMENT=prod
AP_FRONTEND_URL=http://192.168.146.128:8100
AP_WEBHOOK_TIMEOUT_SECONDS=30
AP_TRIGGER_DEFAULT_POLL_INTERVAL=5
AP_POSTGRES_DATABASE=activepieces
AP_POSTGRES_HOST=postgres
AP_POSTGRES_PORT=5432
AP_POSTGRES_USERNAME=postgres
AP_POSTGRES_PASSWORD=ed57ea101a38683c4733ff9d1aefdbede007e3ac558548fc9f503beeda805d80
AP_EXECUTION_MODE=UNSANDBOXED
AP_REDIS_HOST=redis
AP_REDIS_PORT=6379
AP_FLOW_TIMEOUT_SECONDS=600
AP_TELEMETRY_ENABLED=true
AP_TEMPLATES_SOURCE_URL="https://cloud.activepieces.com/api/v1/flow-templates"
EOF

（以上为实测部署真实使用的 .env 内容；密钥为本环境专用随机值，请替换为你自己生成的。）

3.3 AP_* 环境变量逐项解说

变量	示例值	必填	说明
AP_CONTAINER_TYPE	APP / WORKER / WORKER_AND_APP	是（在编排文件中指定）	服务角色开关：APP 只跑 API 与前端；WORKER 只跑执行器；WORKER_AND_APP 单进程全包
AP_ENGINE_EXECUTABLE_PATH	dist/packages/engine/main.js	是	执行引擎入口路径，官方默认值照抄即可
AP_API_KEY	openssl rand -hex 64	否	服务间/云 API 密钥；社区版自部署场景可以不填
AP_ENCRYPTION_KEY	openssl rand -hex 16	是	连接器凭据、连接值等敏感数据的加密密钥，32 位 hex，丢失后凭据不可恢复
AP_JWT_SECRET	openssl rand -hex 32	是	登录会话令牌签名密钥
AP_ENVIRONMENT	prod	是	运行环境标识，生产固定 prod
AP_FRONTEND_URL	http://192.168.146.128:8100	是	对外访问地址，Webhook 回调与邮件中的链接都用它拼接，必须与实际访问地址一致
AP_WEBHOOK_TIMEOUT_SECONDS	30	否	同步等待 Webhook 执行结果的超时秒数
AP_TRIGGER_DEFAULT_POLL_INTERVAL	5	否	轮询类触发器的默认轮询间隔（秒）
AP_POSTGRES_DATABASE / HOST / PORT / USERNAME / PASSWORD	见上	是	数据库四要素；HOST 用 Compose 服务名 postgres
AP_EXECUTION_MODE	UNSANDBOXED	是	代码步骤执行模式：UNSANDBOXED 直接跑在 Worker 内（快）；SANDBOXED 跑在隔离沙箱（更安全，略慢）
AP_REDIS_HOST / AP_REDIS_PORT	redis / 6379	是	Redis 地址端口；HOST 用 Compose 服务名 redis
AP_FLOW_TIMEOUT_SECONDS	600	否	单次流运行的最大时长（秒）
AP_TELEMETRY_ENABLED	true	否	匿名遥测上报开关，内网环境可设 false
AP_TEMPLATES_SOURCE_URL	官方模板库地址	否	画布"模板"页的数据源，内网环境可指向私有模板服务
AP_SANDBOX_PROPAGATED_ENV_VARS 等 AP_SANDBOX_*	按需	否	SANDBOXED 模式下沙箱进程的环境变量白名单、内存与时长上限

另外两个在编排文件里出现的环境变量：POSTGRES_DB/POSTGRES_USER/POSTGRES_PASSWORD 是 PostgreSQL 官方镜像的初始化变量（首次建库用），与 AP_POSTGRES_* 一一对应、值保持一致。

四、编排文件与启动

4.1 docker-compose.yml 全文

部署目录结构如下：

/opt/deploy/activepieces/
├── docker-compose.yml
├── .env
└── cache/            # 引擎工作目录（挂载进 app/worker）

docker-compose.yml 全文（实测部署原样）：

services:
  app:
    image: ghcr.io/activepieces/activepieces:0.92.3
    container_name: activepieces-0.92.3-app
    restart: unless-stopped
    ports:
      - '8100:80'
    depends_on:
      - postgres
      - redis
    env_file: .env
    environment:
      - AP_CONTAINER_TYPE=APP
      - NODE_USE_ENV_PROXY=1
      - HTTP_PROXY=http://192.168.1.62:7897
      - HTTPS_PROXY=http://192.168.1.62:7897
      - NO_PROXY=localhost,127.0.0.1,postgres,redis,app,10.89.27.0/24,192.168.146.0/24
    volumes:
      - ./cache:/usr/src/app/cache
    networks:
      - activepieces
  worker:
    image: ghcr.io/activepieces/activepieces:0.92.3
    container_name: activepieces-0.92.3-worker
    restart: unless-stopped
    depends_on:
      - app
    env_file: .env
    environment:
      - AP_CONTAINER_TYPE=WORKER
      - NODE_USE_ENV_PROXY=1
      - HTTP_PROXY=http://192.168.1.62:7897
      - HTTPS_PROXY=http://192.168.1.62:7897
      - NO_PROXY=localhost,127.0.0.1,postgres,redis,app,10.89.27.0/24,192.168.146.0/24
    volumes:
      - ./cache:/usr/src/app/cache
    networks:
      - activepieces
  postgres:
    image: 'pgvector/pgvector:0.8.0-pg14'
    container_name: activepieces-0.92.3-postgres
    restart: unless-stopped
    env_file: .env
    environment:
      - 'POSTGRES_DB=${AP_POSTGRES_DATABASE}'
      - 'POSTGRES_PASSWORD=${AP_POSTGRES_PASSWORD}'
      - 'POSTGRES_USER=${AP_POSTGRES_USERNAME}'
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - activepieces
  redis:
    image: 'redis:7.0.7'
    container_name: activepieces-0.92.3-redis
    restart: unless-stopped
    volumes:
      - 'redis_data:/data'
    networks:
      - activepieces
volumes:
  postgres_data:
  redis_data:
networks:
  activepieces:
    name: s3-activepieces_apnet
    ipam:
      config:
        - subnet: 10.89.27.0/24

逐项解说：

app：对外唯一入口，8100:80 把宿主 8100 映射到官方监听的 80 端口；AP_CONTAINER_TYPE=APP 声明角色；./cache 挂载用于引擎临时产物。其中 NODE_USE_ENV_PROXY 与 HTTP(S)_PROXY 三行是实测环境出口网络质量不稳时添加的代理配置，可直连 ghcr.io 与 npm registry 的服务器请删除这三行与 NO_PROXY 行；
worker：与 app 用同一镜像，仅 AP_CONTAINER_TYPE=WORKER 不同，不映射任何端口（执行器只通过 Redis 队列接活）。需要水平扩容时复制一个 worker 服务并把 container_name 改开即可；
postgres：官方要求 pgvector 变体镜像（内置向量扩展，支撑 AI 能力）；数据通过命名卷 postgres_data 持久化；POSTGRES_* 三个变量通过 ${AP_POSTGRES_*} 从 .env 读取，保证数据库口令只维护一处；
redis：队列与锁服务，数据卷 redis_data 保存任务队列，避免重启丢任务；
networks：统一挂到第二步创建的 s3-activepieces_apnet（10.89.27.0/24）。

4.2 拉取镜像并校验编排

docker compose pull

实测回显：

 Image ghcr.io/activepieces/activepieces:0.92.3 Pulling
 Image pgvector/pgvector:0.8.0-pg14 Pulling
 Image redis:7.0.7 Pulled
 Image ghcr.io/activepieces/activepieces:0.92.3 Pulled
 Image pgvector/pgvector:0.8.0-pg14 Pulled

先做一次编排语法与变量插值校验（不会启动服务）：

docker compose config --quiet && echo 'COMPOSE CONFIG OK'

实测回显：

COMPOSE CONFIG OK

4.3 启动服务

docker compose up -d

实测回显（服务已运行时的幂等输出；首次启动会显示 Network ... Created 与 Container ... Started）：

 Container activepieces-0.92.3-redis Running
 Container activepieces-0.92.3-app Running
 Container activepieces-0.92.3-worker Running
 Container activepieces-0.92.3-postgres Running

4.4 启动状态与就绪验证

等待约 30 秒让数据库完成建表迁移，然后确认四个服务的运行状态：

docker compose ps --format 'table {{.Name}}\t{{.Image}}\t{{.Status}}'

实测回显：

NAME                           IMAGE                                      STATUS
activepieces-0.92.3-app        ghcr.io/activepieces/activepieces:0.92.3   Up 8 minutes (healthy)
activepieces-0.92.3-postgres   pgvector/pgvector:0.8.0-pg14               Up 9 minutes
activepieces-0.92.3-redis      redis:7.0.7                                Up 47 minutes
activepieces-0.92.3-worker     ghcr.io/activepieces/activepieces:0.92.3   Up 8 minutes (healthy)

app 与 worker 自带健康检查，healthy 即 API 就绪。再从应用日志确认监听与迁移情况：

docker logs activepieces-0.92.3-app 2>&1 | head -6

实测回显：

AP_CONTAINER_TYPE: APP
AP_PORT: 80
Auto-generating AP_WORKER_TOKEN...
Starting Activepieces (APP mode)
[dotenv@17.2.3] injecting env (0) from packages/.env.dev -- tip: 🔐 prevent committing .env to code: https://dotenvx.com/precommit
{"timestamp":"2026-10-18T09:07:50.863Z","level":"info","service":"activepieces-api","environment":"prod","version":"0.92.3","msg":"Seeding roles","name":"rolesSeed"}

docker logs activepieces-0.92.3-app 2>&1 | grep -m1 'listening'

实测回显：

{"timestamp":"2026-10-18T09:07:51.341Z","level":"info","service":"activepieces-api","environment":"prod","version":"0.92.3","msg":"Server listening at http://[::]:80"}

最后验证官方健康检查端点与 Web UI：

curl -s -m 15 http://192.168.146.128:8100/api/v1/health

实测回显：

{"status":"Healthy"}

curl -s -m 15 http://192.168.146.128:8100/ | grep -oE '<title>[^<]*</title>'

实测回显：

<title>Activepieces</title>

健康端点返回 Healthy、页面标题正常，说明 API、数据库、Redis 链路全部就绪。

五、首个账号注册与初始化验证

部署完成后第一件事是注册管理员（第一个注册的用户自动成为平台管理员）。既可以在浏览器完成，也可以用 REST API 验证（后续做自动化验收更方便），本节用 API 实测：

curl -s -m 15 -X POST http://192.168.146.128:8100/api/v1/authentication/sign-up \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4","firstName":"Admin","lastName":"User","trackEvents":false,"newsLetter":false}' \
  -w '\nHTTP_STATUS:%{http_code}\n' | python3 -c "
import sys,json
raw=sys.stdin.read()
body,_,tail=raw.rpartition('HTTP_STATUS:')
d=json.loads(body)
print('注册邮箱:', d.get('email'))
print('平台角色:', d.get('platformRole'))
print('创建的项目 id:', d.get('projectId'))
print('HTTP_STATUS:'+tail)
"

实测回显：

注册邮箱: admin@example.com
平台角色: ADMIN
创建的项目 id: ptCNUnkh0eHoNtIFJWA2C
HTTP_STATUS:200

再用同一账号走一次登录验证凭据与会话签发：

curl -s -m 15 -X POST http://192.168.146.128:8100/api/v1/authentication/sign-in \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4"}' | python3 -c "
import sys,json
d=json.load(sys.stdin)
print('token 前缀:', d['token'][:30]+'...')
"

实测回显：

token 前缀: eyJhbGciOiJIUzI1NiIsInR5c...

六、数据持久化与重启验证

所有业务数据都在 PostgreSQL 命名卷里，先确认卷已创建并挂载：

docker volume ls --format '{{.Name}}' | grep deploy

实测回显：

deploy_postgres_data
deploy_redis_data

docker inspect deploy_postgres_data --format '挂载点: {{.Mountpoint}} | 驱动: {{.Driver}}'

实测回显：

挂载点: /var/lib/docker/volumes/deploy_postgres_data/_data | 驱动: local

做一次破坏性验证：重启数据库与应用（模拟服务器重启场景），确认账号与数据不丢。重启前先用 0.92.3 登录拿到会话（见第五章），重启后查工作流数量与运行历史：

docker compose restart postgres && sleep 8 && docker compose restart app

实测回显：

 Container activepieces-0.92.3-postgres Started
 Container activepieces-0.92.3-app Started

curl -s -m 15 http://192.168.146.128:8100/api/v1/health

实测回显：

{"status":"Healthy"}

docker exec activepieces-0.92.3-postgres psql -U postgres -d activepieces -tAc "SELECT count(*) FROM flow;"

实测回显：

重启后健康检查通过、flow 表数据完好（实测库中 6 条工作流全部保留），持久化验证通过。数据库当前规模参考：83 张业务表、约 301 MB（含运行历史）。

七、版本升级实测

Activepieces 的升级就是"换镜像 tag + 重建服务"，数据库 schema 由服务启动时自动迁移。为验证升级路径，本节先把部署回退到旧版 0.92.2 模拟存量环境，再执行标准的 0.92.2 → 0.92.3 升级。

第一步，拉取旧版并切换：

docker pull ghcr.io/activepieces/activepieces:0.92.2

实测回显：

Status: Downloaded newer image for ghcr.io/activepieces/activepieces:0.92.2

sed -i 's/ghcr.io\/activepieces\/activepieces:0.92.3/ghcr.io\/activepieces\/activepieces:0.92.2/g' docker-compose.yml
docker compose up -d

实测回显：

 Container activepieces-0.92.3-app Starting
 Container activepieces-0.92.3-app Started
 Container activepieces-0.92.3-worker Starting
 Container activepieces-0.92.3-worker Started

第二步，确认旧版可用后执行标准升级流程——改回新 tag、重建：

sed -i 's/ghcr.io\/activepieces\/activepieces:0.92.2/ghcr.io\/activepieces\/activepieces:0.92.3/g' docker-compose.yml
docker compose up -d

实测回显：

 Container activepieces-0.92.3-app Starting
 Container activepieces-0.92.3-app Started
 Container activepieces-0.92.3-worker Starting
 Container activepieces-0.92.3-worker Started

第三步，验证升级结果。等待 30 秒后依次检查健康、迁移日志、数据完整性：

curl -s -m 15 http://192.168.146.128:8100/api/v1/health

实测回显：

{"status":"Healthy"}

docker logs --since 1m activepieces-0.92.3-app 2>&1 | grep -iE 'migrat' | tail -5

实测回显：

{"timestamp":"2026-10-18T09:07:51.344Z","level":"info","service":"activepieces-api","environment":"prod","version":"0.92.3","msg":"[unifyOldQueuesIntoOne] Already migrated, skipping"}
{"timestamp":"2026-10-18T09:07:51.345Z","level":"info","service":"activepieces-api","environment":"prod","version":"0.92.3","msg":"[removeRateLimitJobsQueue] Already migrated, skipping"}
{"timestamp":"2026-10-18T09:07:51.345Z","level":"info","service":"activepieces-api","environment":"prod","version":"0.92.3","msg":"[refillPausedRuns] Already migrated, skipping"}
{"timestamp":"2026-10-18T09:07:51.345Z","level":"info","service":"activepieces-api","environment":"prod","version":"0.92.3","msg":"[deleteStaleRunMetadata] Already migrated, skipping"}
{"timestamp":"2026-10-18T09:07:51.345Z","level":"info","service":"activepieces-api","environment":"prod","version":"0.92.3","msg":"[deleteLegacyRedisKeys] Already migrated, skipping"}

docker exec activepieces-0.92.3-postgres psql -U postgres -d activepieces -tAc "SELECT count(*) FROM flow;"

实测回显：

Already migrated, skipping 说明 schema 迁移幂等可重入；升级前后 flow 数量一致、登录与 API 全部正常。升级实操要点：

升级前先备份 PostgreSQL 数据卷（docker run --rm -v deploy_postgres_data:/data -v /backup:/backup ubuntu tar czf /backup/pg-$(date +%F).tgz -C /data .）；
0.x 阶段小版本升级通常平滑；跨多个大版本（如 0.85 → 0.92）建议逐版本滚动升级并阅读 Release Notes；
升级只改镜像 tag，.env 与数据卷不动，回滚即把 tag 改回去再 up -d。

八、可选：单容器形态部署

小规格场景（一台低配服务器、演示环境）可以把 API 与 Worker 合并为一个服务，编排文件缩减为三服务结构，只改两处：

app 服务的 AP_CONTAINER_TYPE 改为 WORKER_AND_APP，删除 worker 服务；
其余环境变量与数据库、Redis 配置不变。

实测在本机独立网络中部署过一套单容器形态（宿主端口 8101），启动日志与角色确认：

docker logs activepieces-0.92.3-allinone 2>&1 | grep -E 'AP_CONTAINER_TYPE|Starting'

实测回显：

AP_CONTAINER_TYPE: WORKER_AND_APP
AP_PORT: 80
Auto-generating AP_WORKER_TOKEN...
Starting Activepieces (WORKER_AND_APP mode)

验证健康与注册（独立数据库，因此是独立的管理员账号）：

curl -s -m 15 http://192.168.146.128:8101/api/v1/health

实测回显：

{"status":"Healthy"}

curl -s -m 20 -X POST http://192.168.146.128:8101/api/v1/authentication/sign-up \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4","firstName":"Admin","lastName":"User","trackEvents":false,"newsLetter":false}' \
  -w '\nHTTP_STATUS:%{http_code}\n' | python3 -c "
import sys,json
raw=sys.stdin.read()
body,_,tail=raw.rpartition('HTTP_STATUS:')
d=json.loads(body)
print('注册邮箱:', d.get('email'), '| 平台角色:', d.get('platformRole'))
print('HTTP_STATUS:'+tail)
"

实测回显：

注册邮箱: admin@example.com | 平台角色: ADMIN
HTTP_STATUS:200

单容器形态功能完整，代价是 API 与执行争抢同一进程资源，建议仅在轻负载场景使用；正式环境仍推荐本文主推的 APP + WORKER 分离结构。

九、常见问题

9.1 缺 AP_REDIS_HOST：启动直接失败（fail-fast）

模拟漏配 Redis 地址，启动日志报错：

{"timestamp":"2026-10-18T09:00:50.153Z","level":"error","service":"activepieces-api","environment":"prod","version":"0.92.3","msg":"[main#start] Failed to start server","error":"Host is required is null or undefined\nError: Host is required is null or undefined\n    at assertNotNullOrUndefined (/usr/src/app/packages/core/utils/src/lib/assertions.ts:18:15)\n    at createStandaloneRedisConnection (/usr/src/app/packages/server/api/src/app/database/redis/default-redis.ts:30:29)"}

处理：在 .env 补上 AP_REDIS_HOST=redis（Compose 网络内用服务名），docker compose up -d 重建。

9.2 缺 AP_REDIS_PORT：同类报错，位置在下一行校验

{"level":"error","msg":"[main#start] Failed to start server","error":"Port is required is null or undefined\nError: Port is required is null or undefined\n    at assertNotNullOrUndefined (...)\n    at createStandaloneRedisConnection (/usr/src/app/packages/server/api/src/app/database/redis/default-redis.ts:31:29)"}

处理：补 AP_REDIS_PORT=6379。Redis 的 Host/Port 两个变量是启动最前段校验的必填项，漏任何一个都会以同样形式 fail-fast。

9.3 缺 AP_POSTGRES_PORT：明确的"属性未定义"报错

{"level":"error","msg":"[main#start] Failed to start server","error":"SYSTEM_PROP_NOT_DEFINED: System property AP_POSTGRES_PORT is not defined, please check the documentation"}

处理：补 AP_POSTGRES_PORT=5432。注意这类报错会指名道姓缺哪个变量，按提示逐个补齐即可；PostgreSQL 的 Database/Username/Password/Port 四项都是启动必填。

9.4 缺 AP_ENCRYPTION_KEY：启动失败的最后一道校验

{"level":"error","msg":"[main#start] Failed to start server","error":"{\"message\":\"AP_ENCRYPTION_KEY is missing or invalid. It must be a 32-character hexadecimal string (representing 16 bytes). You can generate one using the command: `openssl rand -hex 16`\",\"docUrl\":\"https://www.activepieces.com/docs/install/configuration/environment-variables\"}"}

处理：执行 openssl rand -hex 16 生成密钥写入 .env。报错自带生成命令与文档链接，非常友好；再次强调该密钥投入使用后不可更换（否则已加密的连接器凭据全部不可解密）。以上四例均实测复现，错误信息按"Redis Host → Redis Port → Postgres 各项 → 加密密钥"的顺序依次暴露，排障时按报错顺序逐个补齐即可。

9.5 宿主端口被占用

docker compose up -d 报 port is already allocated 时，用 ss -ltnp | grep ':<端口>' 找到占用进程；本环境实测 8096 被占用，顺延改用 8100。改动只涉及编排文件的 ports 段与 .env 的 AP_FRONTEND_URL，两处保持一致。

9.6 出口网络受限导致 piece 同步失败

服务启动后日志若出现 piece 同步（Piece synchronization）报错、或代码步骤安装依赖失败，多为服务器访问 npm registry / cloud.activepieces.com 不稳。处理办法是在 app 与 worker 的 environment 中增加（Node 24 起支持 NODE_USE_ENV_PROXY）：

      - NODE_USE_ENV_PROXY=1
      - HTTP_PROXY=http://<代理地址>:<端口>
      - HTTPS_PROXY=http://<代理地址>:<端口>
      - NO_PROXY=localhost,127.0.0.1,postgres,redis,app,<宿主内网段>

本环境实测加入代理配置后同步恢复正常（同步后可用 piece 数量从 0 增至 769）。可直连的部署环境无需这些变量。

9.7 worker 反复报 Socket.IO connection error

单容器或 worker 启动早期日志可能刷 Socket.IO connection error: websocket error，这是 worker 在等 API 就绪（本环境实测 all-in-one 形态启动早期出现过），API 完成迁移监听后会自动恢复；若持续超过 2 分钟，检查 app 容器是否启动失败（按 9.1–9.4 排查）。

十、参考链接

官方部署文档（Docker）：https://www.activepieces.com/docs/install/docker
环境变量官方说明：https://www.activepieces.com/docs/install/configuration/environment-variables
官方 docker-compose 参考：https://github.com/activepieces/activepieces/blob/main/docker-compose.yml
Release 列表（版本核实）：https://github.com/activepieces/activepieces/releases
pgvector 镜像：https://hub.docker.com/r/pgvector/pgvector
本组件认知篇：《Activepieces 0.92.3 介绍与选型指南》