Activepieces 自托管如何用 Nginx 反向代理完成 HTTPS 证书与 WebSocket 代理配置？-编程实验室

Activepieces 自托管如何用 Nginx 反向代理完成 HTTPS 证书与 WebSocket 代理配置？

【免费下载链接】activepiecesAI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces

自托管 Activepieces（例如通过 Docker Compose 安装）后，应用默认只在http://localhost:8080上以 HTTP 提供服务。如果你的服务器需要一个域名并对外提供 HTTPS，同时要保证界面里的 WebSocket 长连接（Test Flow、实时运行更新）正常工作，就需要在应用前面架一层反向代理来终结 TLS。Activepieces 官方文档给出的方案是用 Nginx 做反向代理：证书放在 Nginx 上，443 流量代理到localhost:8080，并在代理头中带上 WebSocket 升级所需字段。

这套教程适用前提是：你自行管理证书（通常是 Community Edition 自托管），且没有托管平台、云负载均衡或 Kubernetes ingress 替你处理 TLS——文档明确说明，如果你的环境已经有这些组件，可以直接跳过本流程。

准备条件

开始前确认三件事，均对应文档中的要求：

Activepieces 已通过 Docker Compose 方式安装并正常启动。默认 compose 文件把容器内 80 端口映射到主机8080（'8080:80'），健康检查命令为：
```
curl http://localhost:8080/api/v1/health
```
该端点有响应说明应用层就绪。如果你安装时用--port改过宿主机端口，下文 Nginx 配置中的proxy_pass目标端口要相应调整。
你已经拥有域名的证书。文档假设证书已存在，并提到可以用 Cloudflare，或用 Let's Encrypt / Certbot 签发。
你准备修改的 Nginx 配置文件是/etc/nginx/sites-available/default，以下所有sudo命令都需要管理员权限，会修改系统包或系统配置，执行前请确认目标机器。

安装 Nginx

在服务器上执行（以 Ubuntu/Debian 的 apt 为例，来自官方文档）：

sudo apt-get install nginx

放置证书文件

文档要求把证书放到固定路径，Nginx 配置会直接引用它们：

私钥：/etc/key.pem
证书：/etc/cert.pem

把你自己域名的证书内容写入这两个文件即可，路径不要改动。

配置 Nginx：80 跳转、443 终结 TLS、代理到 8080

编辑配置文件：

sudo nano /etc/nginx/sites-available/default

文档给出的完整配置如下，server_name中的example.com替换为你的实际域名：

server { listen 80; listen [::]:80; server_name example.com www.example.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name example.com www.example.com; ssl_certificate /etc/cert.pem; ssl_certificate_key /etc/key.pem; location / { proxy_pass http://localhost:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } }

这段配置里有三个部分各司其职，缺任何一部分都会出问题：

第一个server块：监听 80，把所有 HTTP 请求 301 跳转到 HTTPS。
ssl_certificate/ssl_certificate_key：在 Nginx 层终结 TLS，对应上一步放进/etc/cert.pem和/etc/key.pem的证书。
location /中的代理头：proxy_pass http://localhost:8080指向 Activepieces 的宿主机端口；而Upgrade、Connection 'upgrade'、proxy_http_version 1.1这组头是 WebSocket 代理的关键——Activepieces 的 WebSocket 连接（Socket.IO）正是依赖这些头才能穿过代理。官方 WebSocket 故障排查文档指出：Test Flow 按钮不工作、流程中的 Test step 不工作、实时更新不显示，这些症状"很可能就是反向代理的 WebSocket 配置不正确"，并直接引用本页配置作为正确示例。

重启 Nginx 并验证

sudo systemctl restart nginx

验证方式按文档是：访问你的域名，应该看到应用带 SSL 运行（即https://你的域名能打开 Activepieces 界面）。再对照 WebSocket 相关症状确认长连接正常：Test Flow 能执行、Test step 有结果、运行日志实时更新。如果界面能打开但上述功能异常，优先回到 Nginx 配置核对Upgrade相关的代理头是否完整。

另一个文档提到的边界情况：部分浏览器会阻止http（非 TLS）的 WebSocket 连接，所以仅在本机以 HTTP 直连时看到的连接失败，换成这套 HTTPS 代理后应随之解决。

把 AP_FRONTEND_URL 指向公网 HTTPS 地址

Nginx 配好后还有关键一步：Activepieces 用AP_FRONTEND_URL构造 OAuth 重定向 URL 和 webhook URL，文档强调它"必须可被第三方访问"。证书上锁之前，如果你的.env里AP_FRONTEND_URL还是 IP 或 ngrok 之类的临时地址，应改成最终的公网 HTTPS 地址，例如：

AP_FRONTEND_URL=https://example.com

修改后重启容器使配置生效。注意一个文档明确指出的坑：AP_FRONTEND_URL对浏览器意味着"你的 app"，但对 worker 容器意味着"它自己"——在手动 compose 流程中，worker 需要单独的覆盖值AP_FRONTEND_URL=http://app（Docker 网络内的 app 服务名），否则 worker 连不上 socket、Workers 页面会是空的。用一条命令脚本安装的部署以生成的.env为准，遇到 Workers 列表为空时按 Docker Compose 自托管文档的 Troubleshooting 一节处理。

改完后可从两个层面复核：

docker compose -p activepieces ps curl http://localhost:8080/api/v1/health

四个容器（app、worker、postgres、redis）都是Up且健康端点有响应，再从浏览器访问https://你的域名，即完成整套配置。

Activepieces 自托管如何用 Nginx 反向代理完成 HTTPS 证书与 WebSocket 代理配置？