Actual Budget 服务器启用 HTTPS 完整指南证书获取、配置方式与源码原理【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual本指南围绕 Actual Budget 自托管服务器的 HTTPS 激活展开覆盖自签名证书与不暴露公网即可获得受信任证书的两种途径并详细讲解config.json、环境变量与桌面客户端三种配置方式。读完本文你将能够为自己的 Actual 实例安全启用 HTTPS并理解配置在packages/sync-server中的加载与生效机制避免常见的证书与健康检查踩坑。何时需要启用 HTTPSActual 的部分功能依赖 HTTPS 才能安全使用例如通过浏览器访问预算数据、与桌面客户端建立加密连接等。官方文档明确指出两种不需要执行本指南步骤的情况仅在本地访问你在自己的电脑上运行服务器且只通过localhost访问云服务商已代管 HTTPS你使用的云平台已自动为实例配置了 HTTPS。除此之外只要是自托管且需要从其他设备访问尤其是跨网络访问都建议按本文步骤启用 HTTPS确保数据在传输过程中加密。1. 获取服务器证书有两种主流获取证书的途径二者共同的前提是不需要把 Actual 直接暴露到公网。如果希望将实例开放给互联网访问则更适合采用反向代理方案参见 reverse-proxies.md。方式一自签名证书自签名证书是让 HTTPS 最快生效的办法代价是浏览器会弹出证书不受信任的警告此外如果私钥泄露攻击者可能拦截你电脑上的大部分加密流量因此务必妥善保管私钥文件。有两种生成方式可选使用 mkcert 自动生成mkcert 这类命令行工具可以自动完成本地证书的创建与系统信任安装一条命令即可生成可用的自签名证书适合本地测试环境。使用 OpenSSL 手动生成在已安装 OpenSSL 的操作系统终端中执行openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout selfhost.key -out selfhost.crt参数说明参数含义req -x509生成自签名 X.509 证书而非证书签名请求-nodes私钥不加密No DES避免服务启动时需要输入密码-days 365证书有效期 365 天到期后需重新生成-newkey rsa:2048同时生成 2048 位 RSA 私钥-keyout selfhost.key私钥输出文件-out selfhost.crt证书输出文件执行后需要输入一个两位字母的国家代码才能生成.crt文件其余字段地区、组织等可以直接按回车留空。生成后把selfhost.key与selfhost.crt移动到 Actual 服务器可以访问的位置例如下文提到的/data目录。自签名证书下的健康检查适配使用自签名证书时Docker Compose 中的健康检查命令需要信任该证书。可以参考 docker-compose.yml 中的写法在 healthcheck 的test中通过NODE_EXTRA_CA_CERTS注入证书路径test: [ CMD-SHELL, NODE_EXTRA_CA_CERTS/data/selfhost.crt node src/scripts/health-check.js, ]之所以需要这一步是因为健康检查脚本会通过https协议请求/health端点源码见 health-check.ts而 Node 默认不会信任自签名证书若不指定 CA 会直接失败。方式二不暴露公网获取受信任证书如果不想接受浏览器的安全警告可以使用支持DNS Challenge的服务来签发受信任的证书Tailscale内置 HTTPS 功能可在其私有网络中为节点签发有效证书Caddy通过自动 HTTPS 的 DNS Challenge 方式为域名签发证书无需开放入站端口。这类方案的核心思路是证书签发机构仅通过 DNS 记录验证域名所有权服务器自身无需暴露到公网从而同时满足受信任证书与不暴露实例两个目标。2. 配置 Actual 使用证书拿到证书后需要把证书路径或内容交给 Actual Sync Server。官方支持三种方式config.json文件、环境变量、桌面客户端内配置。方式一config.json文件在运行 Actual Sync Server 的目录下创建config.json若从源码构建该目录为packages/sync-server/参见 build-from-source.md填入.key与.crt文件的路径{ https: { key: /data/selfhost.key, cert: /data/selfhost.crt } }关于路径的注意点如果使用 Docker 或类似容器环境务必确认证书路径在容器内可访问。Docker 容器中 Actual 的数据目录固定为/data当你挂载宿主目录到该路径时把config.json放在宿主挂载目录下即可容器内即/data/config.json证书文件也放入同一目录以保持路径一致。在 macOS/类 Unix 系统的终端中可以用下面的命令直接在当前目录生成config.jsoncat EOF | tee config.json { https: { key: /data/selfhost.key, cert: /data/selfhost.crt } } EOF方式二环境变量如果不方便创建配置文件可以通过环境变量直接传入证书内容而非路径环境变量对应配置项值ACTUAL_HTTPS_KEYhttps.key私钥文件内容PEMACTUAL_HTTPS_CERThttps.cert证书文件内容PEM如果所用环境不允许在变量值中包含换行符可以把换行替换为字面量\nActual 会自动将其还原为真实换行。这一设计在源码中有直接体现加载配置时https.key与https.cert两个设置项分别映射到ACTUAL_HTTPS_KEY/ACTUAL_HTTPS_CERT环境变量见 load-config.js而服务器启动时app.ts 中的parseHTTPSConfig会判断取值若以-----BEGIN开头则视为 PEM 内容直接使用否则视为文件路径读取。这正是config.json写路径、环境变量传内容两种方式能共存于同一配置项的底层原因。方式三桌面客户端配置在桌面应用的Wheres the server?服务器在哪里界面中操作输入你的服务器 URL点击 OK若弹出要求选择证书的错误提示选择对应证书后重试。使用 mkcert 时的特别说明如果证书由 mkcert 生成应选择mkcert 的根 CA 证书而不是服务器实际使用的那个证书。操作步骤执行mkcert -CAROOT找到根证书所在目录进入该目录找到rootCA.pem证书文件在桌面客户端中指定该rootCA.pem。3. 测试 HTTPS完成证书获取与配置后验证是否生效访问你的实例地址务必使用https://前缀推荐重新输入服务器 URL或新开一个标签页/窗口访问而不是在之前报错的页面直接刷新。若使用自签名证书浏览器会显示安全警告确认证书指纹无误后手动信任即可继续。源码视角HTTPS 是如何被加载与生效的理解配置的完整链路有助于排查问题。以下均来自当前仓库packages/sync-server的实现配置加载阶段load-config.js 使用 convict 定义配置 schemahttps对象包含key与cert两个字段。配置文件查找顺序为ACTUAL_CONFIG_PATH指定的路径 → 项目根目录config.json→ 数据目录config.json数据目录默认取/data若不存在则回退到项目根目录见 load-config.js 与 load-config.js。启动生效阶段app.ts 的run()函数中只有当https.key与https.cert同时非空时才会走node:https的createServer分支启动 TLS 服务否则回退到普通的app.listen。也就是说证书只配置了一半只有一个字段时服务器会静默退回 HTTP这也是测试阶段最常遇到的配置了却没生效的原因。健康检查阶段health-check.ts 会根据https.key https.cert是否同时存在来决定用https还是http协议请求/health并要求返回{status:UP}才算通过。其他可用配置项https对象除了key/cert还支持透传 Node.jstls.createServer()、tls.createSecureContext()与http.createServer()的可选参数如ca、passphrase等大多数自托管场景无需使用完整的配置项清单可查阅 config/index.md。常见问题速查配置了 HTTPS 但访问仍是 HTTP检查https.key与https.cert是否同时配置任一缺失都会回退到 HTTP依据 app.ts 的判断逻辑。Docker 下提示找不到证书文件确认证书路径是容器内路径挂载后通常为/data/...而不是宿主机的绝对路径。健康检查一直失败自签名证书场景需按本文第一节补充NODE_EXTRA_CA_CERTS环境变量参考 docker-compose.yml。桌面端始终提示证书错误若使用 mkcert确认选择的是根 CA 的rootCA.pem而非服务器证书本身。至此你的 Actual 实例已经可以通过 HTTPS 安全访问浏览器端与桌面客户端的加密连接均已就绪。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考