AstronRPA 自托管 HTTPS 部署指南：OpenResty 网关 TLS 终结、HTTP 迁移与证书续期-平芜编程栈

工作流自动化
桌面应用
AI 应用
企业应用
后端
前端

【免费下载链接】astron-rpa

Agent-ready RPA suite with out-of-the-box automation tools. Built for individuals and enterprises.

项目地址：https://gitcode.com/bijinfeng/astron-rpa

本篇指南完整讲解 AstronRPA 开源仓库自托管场景下的 HTTPS 部署方案：公网 TLS 由 OpenResty 网关统一终结，容器之间继续走私有 Docker 网络与 HTTP 服务名；默认部署模式为https，legacy-http是显式的明文兼容模式。读完本文你将掌握：DNS 与证书的准备工作、.env关键变量与自定义端口配置、凭据初始化与签名证书轮换、部署验证、存量 HTTP 环境的迁移步骤、临时回滚，以及证书续期后如何安全热加载。

架构总览：TLS 在哪里终结

AstronRPA 的 HTTPS 设计遵循一个清晰的分层原则：公网入口的 TLS 由 OpenResty 网关统一终结，docker-compose.yml中的openresty-nginx服务（镜像openresty/openresty:1.27.1.1-alpine）承载全部对外流量；RPA 各服务（ai-service、openapi-service、resource-service、robot-service、rpa-auth）与 Casdoor 之间则继续使用已有的私有 Docker 网络与 HTTP 服务名通信，例如 docker-compose.yml 中http-common.conf定义的 upstream：

resource-service:8030、robot-service:8040、ai-service:8010、openapi-service:8020、rpa-auth:10251、casdoor:8000

这种"边缘终结 TLS、内部明文 HTTP"的模式避免在每一个业务容器里重复配置证书，同时把 WebSocket 升级、MCP 流式转发、Cookie 安全标志等边界问题集中收敛到网关一层。

默认模式是https；legacy-http是显式、未加密的兼容模式，仅供受控迁移或本地开发。需要强调的是，这是一套自托管部署：服务器、域名注册、DNS 记录、证书/私钥、暴露端口与证书续期都由部署方自行提供和维护，项目只提供应用与配置，不提供共享的托管端点或共享 TLS 凭据。文档中的域名与服务器 IP 均为示例，请全部替换为你实际控制的值。

从实现细节看，网关的配置渲染与校验逻辑集中在 render-config.sh：容器启动时（entrypoint 为["/bin/sh", "/etc/nginx/render-config.sh"]）根据DEPLOYMENT_MODE选择模板，并用sed把@@RPA_SERVER_NAME@@、@@CASDOOR_SERVER_NAME@@、@@RPA_HTTPS_REDIRECT_AUTHORITY@@、@@TLS_CERTIFICATE_FILE@@等占位符替换为.env传入的环境变量，生成conf.d/default.conf后启动 OpenResty。脚本在渲染前还会做三类校验（render-config.sh）：

validate_name：服务名必须是单个 DNS 名、IPv4 地址或下划线；
validate_authority：重定向 authority 只允许主机名加可选端口；
validate_file_name：证书文件名必须落在/etc/nginx/certs目录内，防止路径逃逸。

在https分支中，脚本还会检查证书文件是否存在且非空（render-config.sh），任一条件不满足都会以非零状态退出，容器即启动失败——这是网关的 fail-closed 行为。

1. 准备公网名称与证书

1.1 配置 DNS

首先为网关与认证服务选择公网名称，例如rpa.example.com与auth.example.com，然后完成以下三步：

确认权威 NS：在域名注册商处查看域名当前的权威名称服务器（NS）。保留注册商默认 DNS 服务即可，只有把 DNS 托管迁移到其他提供商时才需要修改 NS。注意 NS 分配只决定"由哪家 DNS 提供商解析"，并不会把某个应用名称指向某台服务器。
添加应用记录：在权威 DNS 提供商处为两个名称分别添加记录。对于拥有公网 IPv4 地址的服务器，典型配置如下：
example.com区域中的记录名类型值 TTL
rpa A 203.0.113.10 提供商默认
auth A 203.0.113.10 提供商默认
203.0.113.10是保留的示例地址（TEST-NET），请替换为你服务器可达的公网 IP 或你运营的入口地址。部分 DNS 控制台要求填写完整名称而非相对名称；当子域指向已有入口主机名时也可改用 CNAME，但不要在同一名称下同时创建 A 与 CNAME。只有入口、监听器与网络路由都已针对 IPv6 配置并验证后，才发布 AAAA 记录——过期的 AAAA 记录即使在 A 记录正确时也可能导致连接失败。
验证解析：在配置 TLS 之前，从客户端网络与 n8n 网络分别验证两个名称：
```
nslookup -type=NS example.com nslookup rpa.example.com nslookup auth.example.com
```
若返回NXDOMAIN或旧地址，先核对记录名与 NS 委派是否生效，再与权威服务器（或公共解析器）对比：
```
nslookup rpa.example.com ns1.dns-provider.example nslookup rpa.example.com 1.1.1.1
```
把ns1.dns-provider.example替换为你实际的权威服务器。若权威服务器返回正确记录而递归解析器没有，需等待其缓存（包括缓存的否定答案）过期；企业 DNS 策略或 split DNS 可能还需要网络管理员协助，反复修改记录并不能清除这些缓存。认证服务名称也要同样验证。

`example.com`区域中的记录名	类型	值	TTL
`rpa`	A	`203.0.113.10`	提供商默认
`auth`	A	`203.0.113.10`	提供商默认

关键认知：DNS 记录里只放 IP 地址或主机名，不能包含https://、端口或 URL 路径。端口在 Compose 与公网 URL 中另行配置；DNS 解析成功本身并不能证明端口可达或 HTTPS 正常工作。

1.2 获取并安装证书

从目标客户端信任的 CA 获取证书，可通过 ACME 客户端或证书提供商的登记流程办理，并按提供商的指引完成对两个名称的控制权验证：

DNS-01：把提供商给出的 TXT 挑战值发布到_acme-challenge.rpa.example.com与_acme-challenge.auth.example.com。这些临时 TXT 记录与应用 A/CNAME 记录是并存关系，并非替代。该方法适用于公网 80/443 端口不可用、或应用使用自定义 HTTPS 端口的场景。提交验证前先确认权威 TXT 解析，验证完成后移除过期的挑战值。
HTTP-01：CA 需要能通过公网 TCP 80 端口访问指定挑战路径。默认 Compose HTTP 映射是仅回环的宿主机 32742 端口，且不提供 ACME 挑战处理器，因此只有当你完全掌控所需公网入口并已配置挑战路由时才使用 HTTP-01；不要为了让它生效而替换其他应用在 80 端口的监听器。

证书的Subject Alternative Name（SAN）必须同时覆盖 AstronRPA 与 Casdoor 两个公网名称。将完整证书链与匹配的私钥复制到docker/certs/（默认文件名为docker/certs/tls.crt与docker/certs/tls.key，可用TLS_CERTIFICATE_FILE/TLS_CERTIFICATE_KEY_FILE修改）。真实证书与私钥会被 Git 忽略，certs/README.md 也明确要求不得提交真实证书。提供的网关配置对两个监听器使用同一套证书/私钥：HTTPS 模式下任一文件缺失、为空或路径配置在/etc/nginx/certs之外，容器都会拒绝启动（见前文 render-config.sh 的 fail-closed 检查）。域名写入证书 SAN，端口号不写入。私钥应在其部署密钥管理中生成和保存，限制文件系统访问并确保网关可读取。

TLS 参数方面，tls-settings.conf 仅启用TLSv1.2 TLSv1.3，开启共享 session 缓存（shared:TLS:10m、超时 1 天）并关闭 session tickets。

1.3 初始化与轮换认证凭据

网关 TLS 证书与 Casdoor 的 token 签名证书职责分离：bootstrap JSON（init_data_dump.json）只提供证书元数据，密钥材料与应用密钥为空；Casdoor 会在自己的数据库中生成独立的签名密钥对与应用密钥。initDataNewOnly=true（见 docker-compose.yml）保证跨重启保留已有密钥、用户与应用设置——导入 JSON不是数据库迁移，不要通过关闭该开关来应用配置变更。

新部署流程：按第 2 节配置.env后，先初始化私有服务再启动 RPA（同步命令要求 Python 3.6+）：

docker compose up -d mysql casdoor # 等待 Casdoor 完成初始化，然后复制本部署的值。 python3 scripts/sync-casdoor-credentials.py docker compose up -d

以上命令需在docker/目录下执行。sync-casdoor-credentials.py的源码逻辑（sync-casdoor-credentials.py）值得展开说明：

通过docker compose config --format json读取rpa-auth服务环境中的CASDOOR_APPLICATION_NAME，向本项目的 MySQL 容器执行一条 SQL，取回应用的client_id、client_secret与所绑定公共签名证书的 PEM（HEX 解码），写入.env的CASDOOR_CLIENT_ID、CASDOOR_CLIENT_SECRET、CASDOOR_CERTIFICATE；
更新采用原子替换（tempfile.mkstemp+os.replace），写入模式0600，不打印任何凭据、不导出签名私钥、不留备份副本；
初始化不完整时（如证书不完整、应用/证书缺失或存在歧义）会直接退出且不修改.env，等 Casdoor 就绪后重试即可；
若 Compose 调用设置了项目名，使用--project-name <existing-project>保持项目一致；脚本固定操作docker/.env，因为服务通过x-env-file加载它，仅用 CLI--env-file不会改变服务挂载来源；所有命令需使用相同的 Compose overrides（例如.env中的COMPOSE_FILE）；Windows 上还需限制该文件的 ACL，POSIX 模式位不能替代 Windows 访问控制。

初始化期间应保持公网入口受限。在 Casdoor 管理界面，必须在开放公网访问前替换默认管理员密码并删除或锁定未使用的示例用户——生成的签名密钥并不能保护仍使用公开默认密码的管理员账号。同时把 Casdoor 数据库及其备份视同私钥库保护。切勿发布.env、数据库导出或docker compose config的输出。

存量部署从旧 bootstrap 升级时，按以下步骤修复：

备份本项目的 Casdoor 数据库与.env（限制访问）。应用净化后的 bootstrap JSON 与initDataNewOnly=true配置，仅重建 Casdoor。这保留了已有数据，但不会轮换已导入的公共密钥或密钥。
通过 Casdoor 已认证的管理 API，为每个受影响的签名证书（包括cert-built-in与example-cert）重新生成certificate与privateKey。Casdoor 的update-cert会在这些字段为空时生成一对新密钥。保持证书名称与签名算法一致，使应用绑定与 default-certificate 回退能选中替换后的密钥。不要保留旧公钥作为可信回退，并单独审查自定义应用/证书。
轮换受影响的客户端密钥（包括内置应用），并替换任何仍为默认值的管理员密码——这是同一次修复的一部分：已知的应用 Secret 可授权 Casdoor API 访问签名材料。保持应用/用户 ID 稳定，并撤销受影响的 OAuth token 与 refresh token；仅轮换签名密钥并不能自动撤销所有已存会话或 refresh-token 记录。
用选定应用的凭据同步 RPA 并重建它：
```
python3 scripts/sync-casdoor-credentials.py docker compose up -d --no-deps --force-recreate rpa-auth
```
SDK 的casdoor.certificate现在来自CASDOOR_CERTIFICATE，不再有共享公钥回退（见 application-casdoor.yml 中casdoor.certificate: ${CASDOOR_CERTIFICATE:}）。当前桌面端登录使用 Casdoor 会话；离线 JWT 消费方也必须替换其信任的公钥。同步命令本身不轮换凭据也不重启服务，同时它也支持内部 HTTP/legacy 模式部署。
验证应用绑定与导出的公钥、新 token 能否被接受、旧签名与旧 Secret 是否被拒绝、客户端登录/WSS 以及 n8n MCP 是否正常；重启 Casdoor 后再次验证以证明持久性。已有 RPA 会话与 n8n API Key 是独立的凭据，签名密钥轮换并不会使它们失效。

所有生成的凭据都应保存在部署存储中、位于受跟踪源码之外。恢复轮换前的数据库备份也会恢复被泄露的签名材料：此类备份只能用于隔离的恢复场景，并在重新开放入口前再次轮换。

2. 配置 HTTPS

复制.env.example为.env，至少设置以下变量（完整模板见 .env.example）：

DEPLOYMENT_MODE="https" RPA_SERVER_NAME="rpa.example.com" CASDOOR_SERVER_NAME="auth.example.com" # 端口不是标准 HTTPS 端口时必须包含端口。 RPA_HTTPS_REDIRECT_AUTHORITY="rpa.example.com" CASDOOR_HTTPS_REDIRECT_AUTHORITY="auth.example.com:8443" RPA_HTTPS_PORT=443 CASDOOR_HTTPS_PORT=8443 CASDOOR_EXTERNAL_ENDPOINT="https://auth.example.com:8443" TLS_CERTIFICATE_FILE="tls.crt" TLS_CERTIFICATE_KEY_FILE="tls.key" SESSION_COOKIE_SECURE=true

各变量语义务必区分清楚：

RPA_SERVER_NAME与CASDOOR_SERVER_NAME只含主机名；
*_HTTPS_REDIRECT_AUTHORITY含外部主机名及任何非标准端口，不带scheme 或路径；
CASDOOR_EXTERNAL_ENDPOINT是完整的公网 HTTPS origin，包括非标准端口；
SESSION_COOKIE_SECURE=true使会话 Cookie 带 Secure 标志，由 docker-compose.yml 注入 rpa-auth，并落到 application-casdoor.yml 的session-cookie-secure: ${SESSION_COOKIE_SECURE:true}；https.conf.template中还会用proxy_cookie_flags casdoor_session_id secure httponly在网关注入 Secure/HttpOnly 标志。

Compose 中网关的端口映射（docker-compose.yml）为：RPA_HTTP_BIND_ADDRESS:32742 → 容器 80、RPA_HTTPS_BIND_ADDRESS:443 → 容器 443、CASDOOR_HTTP_BIND_ADDRESS:8000 → 容器 8080、CASDOOR_HTTPS_BIND_ADDRESS:8443 → 容器 8443。

若直接使用提供的 Compose 网关，需要在云安全组/防火墙（必要时加 NAT 规则）中放行所选 HTTPS 宿主端口。若 443/8443 已被占用，选择可用端口并同步更新所有相关值，例如：

设置	自定义端口示例
`RPA_HTTPS_PORT`	`9443`
`CASDOOR_HTTPS_PORT`	`9444`
`RPA_HTTPS_REDIRECT_AUTHORITY`	`rpa.example.com:9443`
`CASDOOR_HTTPS_REDIRECT_AUTHORITY`	`auth.example.com:9444`
`CASDOOR_EXTERNAL_ENDPOINT`	`https://auth.example.com:9444`
客户端`remote_addr`	`https://rpa.example.com:9443/`
n8n MCP 端点	`https://rpa.example.com:9443/api/rpa-openapi/mcp/`

后端与数据库端口保持私有；共享宿主机上只修改本部署分配到的端口与文件。若使用独立入口（如外部负载均衡），需一致地配置其外部 URL 与端口转发，并支持 WSS 与 MCP 流式传输——DNS 不会自动配置该入口。

CASDOOR_ENDPOINT必须保持内部 HTTP 地址：

CASDOOR_ENDPOINT="http://rpa-opensource-casdoor:8000"

旧的 HTTP 端口默认仅回环绑定并返回308重定向（见 https.conf.template 中两个return 308 https://...$request_uri的 server 块）。迁移期间可临时更改绑定地址将其暴露，但任何凭据都不应发往 HTTP URL。

3. 验证与启动

首次安装需先完成第 1.3 节的 Casdoor 初始化与凭据同步，再启动全栈：

docker compose config --quiet docker compose up -d docker compose ps docker compose logs openresty-nginx curl -I http://127.0.0.1:32742/health curl https://rpa.example.com/health

第一条（回环 HTTP）必须返回308重定向；
第二条必须返回healthy，且证书有效、受信任。

注意容器自身的健康检查走的是内部 8090 端口（docker-compose.yml 与模板中的server { listen 8090; }内部健康块），不会削弱公网 TLS。

随后配置已安装的客户端指向 HTTPS 网关：

remote_addr: https://rpa.example.com/

n8n MCP Client 的 Streamable HTTP 端点配置为https://rpa.example.com/api/rpa-openapi/mcp/，在其 Bearer Credential 中使用 API Key；Key 应保存在凭据库中，而不是 URL 或工作流参数里。自定义端口时按上文表格同步更新客户端、n8n 与验证 URL。使用正常的证书校验，SSH 隧道不是部署要求。

客户端/Scheduler 的远程传输如何从该值派生协议，可在 remote_transport.py 中看到实现：remote_addr只允许 http/https 且不含凭据与查询参数；ws_url按"wss" if origin.scheme == "https" else "ws"派生（remote_transport.py）；HTTPS 客户端通过ssl.create_default_context()使用标准 Python TLS 信任上下文——包含系统根，部署使用私有 CA 时也会加载显式配置的SSL_CERT_FILE。会话 Cookie 按 origin 存储在客户端工作目录的.remote-cookies目录（SessionCookies以sha256(remote_addr)命名 jar 文件，目录权限0700），且只会迁移所配置 origin 的旧.cookie.json会话，不会把临时回环代理的 Cookie 混入其中。

捆绑的二进制仍保留本地模块路由，并通过回环连接该传输；直接把该二进制连到 HTTPS 的旧客户端会跳过证书校验，必须升级。Chromium 也必须去掉历史遗留的ignore-certificate-errors开关运行；若使用私有 CA，应按该 CA 配置 Chromium 的信任库，而不是关闭校验。

4. 迁移现有 HTTP 部署

备份.env与当前 Compose 配置。不需要数据库变更。
在修改公网 URL 之前，准备并验证证书名称。
更新 HTTPS 变量与CASDOOR_EXTERNAL_ENDPOINT。
启动默认 HTTPS 模式，验证/health、登录、MCP Streamable HTTP 与 WebSocket 路由。
把所有调用方更新为 HTTPS 网关地址。
旧 HTTP 端口只保留重定向功能，迁移完成后把其绑定地址恢复为127.0.0.1。

5. 显式 legacy HTTP 兼容模式

legacy-http通过 OpenResty 恢复旧的网关与 Casdoor 明文协议，同时为旧会话 Cookie 关闭 Secure 标志。该模式未加密，仅适用于受控迁移或本地开发。

docker compose -f docker-compose.yml -f docker-compose.legacy-http.yml up -d

该 override（docker-compose.legacy-http.yml）使用 Compose 的!override标签，因此要求 Docker Compose 2.24.4 或更新；它移除未使用的 HTTPS 端口映射，使 legacy 回滚不会占用 443/8443。文件内将DEPLOYMENT_MODE置为legacy-http、SESSION_COOKIE_SECURE置为false，并把CASDOOR_EXTERNAL_ENDPOINT指向LEGACY_CASDOOR_EXTERNAL_ENDPOINT。

已有远端部署若确需明文暴露，必须显式配置：

RPA_HTTP_BIND_ADDRESS="0.0.0.0" CASDOOR_HTTP_BIND_ADDRESS="0.0.0.0" LEGACY_CASDOOR_EXTERNAL_ENDPOINT="http://YOUR_SERVER:8000"

然后用同样的两个 Compose 文件启动。切勿将这种配置用于新的公网安装。

6. 回滚 HTTPS 配置

若因部署特有的证书或名称问题需要临时回滚：

docker compose down docker compose -f docker-compose.yml -f docker-compose.legacy-http.yml up -d

同时把调用方恢复为旧的 HTTP 网关 URL，并将LEGACY_CASDOOR_EXTERNAL_ENDPOINT设为之前的 Casdoor URL。此回滚不需要恢复数据库，也不会删除 Docker 卷。证书或名称问题解决后，应尽快切回 HTTPS。

7. 证书续期与替换

提供的 Compose 栈不负责签发或自动续期证书，部署方必须监控到期时间并在 CA 截止日期前安排续期。仅安装 ACME 客户端或添加网关 reload 钩子，并不能证明无人值守续期真正可用：

手动 DNS-01：CA 要求重新验证时，需再次完成 TXT 挑战；
自动 DNS-01：使用所选 ACME 客户端支持的 DNS 提供商，把其 API 凭据保存在源码控制之外并授予最低所需 DNS 权限，配置由部署方拥有的续期计划。不要假设手动 TXT 配置可以无人值守续期。

续期成功后：

对当前证书与密钥保留受保护备份。把新的完整链与匹配密钥安装到docker/certs/下配置的路径，保持原有权限。ACME 客户端自己目录里的证书在完成此复制/安装步骤之前并未安装到网关。

校验网关配置，仅在校验成功后 reload 本部署的网关：

docker compose exec -T openresty-nginx openresty -t # 仅在前一条命令成功后才执行。 docker compose exec -T openresty-nginx openresty -s reload

对两个公网名称建立全新 HTTPS 连接，核对所服务证书的 SAN、链与有效期；复查客户端登录/WSS 与 n8n MCP 初始化/发现（无需启动 RPA 任务）。仅本地检查证书文件成功，不能证明新证书已在提供服务。
若校验失败：保留正在运行的网关，恢复已保存的文件并修正证书/密钥配置。不要通过禁用 TLS 校验或经 HTTP 发送凭据来绕过续期失败。

ACME 账户密钥、DNS API token、续期状态与私钥备份都应存放在部署的受保护存储中，并记录续期负责人与计划，方便后续运维人员维护。

附：常用运维命令速查

# 查看服务状态 docker compose ps # 跟踪网关日志 docker compose logs -f openresty-nginx # 替换证书前先校验，仅在校验成功后 reload docker compose exec -T openresty-nginx openresty -t docker compose exec -T openresty-nginx openresty -s reload # 停止服务且不删除数据卷 docker compose down

快速起步流程可参考 QUICK_START.md；DNS 设置、证书签发/续期、自定义端口、迁移步骤、验证与回滚的完整细节均以本文（HTTPS_DEPLOYMENT.md）为准。部署的所有命令都应从docker/目录执行，并在整个生命周期内保持相同的项目名、环境与 overrides。