企业官网建设流程全解析

Actual 服务器怎么配置 HTTPS 与请求头以满足 SharedArrayBuffer 条件

【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual

Actual 的 Web 端依赖浏览器 APISharedArrayBuffer。由于现代 CPU 的安全漏洞，浏览器默认禁用该特性，除非服务器满足特定条件——官方文档的结论很直接："Actual will not be able to run unless your server meets these conditions"。需要同时满足的三个条件是：

1. 站点必须通过 HTTPS 提供服务（使用云厂商托管时通常已经帮你完成）；
2. 响应头中必须包含Cross-Origin-Embedder-Policy: require-corp和Cross-Origin-Opener-Policy: same-origin；
3. 访问端浏览器本身必须支持SharedArrayBuffer（较新版本的 Chrome、Firefox、Safari、Edge 均支持）。

第 1、2 条需要你在服务器端完成配置。完整路径是：获取证书 → 让 Actual 使用证书 → 保证两个安全头（自托管反向代理时是关键环节）→ 通过 HTTPS 访问验证。

第一步：获取 SSL 证书

官方文档说明：如果你在本机运行服务器且只通过localhost访问，或云厂商已处理 HTTPS，可以跳过本步。需要证书时，文档给出了两条路线，都适用于不直接暴露到公网的场景。

自签名证书（最简单）

命令行工具 mkcert 可以自动化这个过程。或者用 OpenSSL 手动生成：先为你的系统安装 OpenSSL，然后在终端执行：

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout selfhost.key -out selfhost.crt

生成过程中需要输入一个两字母的国家代码才能生成.crt文件，其余字段直接回车留空即可。完成后把selfhost.key和selfhost.crt放到 Actual 服务器可访问的位置。

自签名证书的两个代价（文档明确提醒）：浏览器会提示证书无效；如果任何人拿到这个证书，就可能拦截你机器上的大部分安全流量。

使用 Tailscale 或 Caddy 获取合法证书

如果你希望获得有效证书但不想把服务器暴露给整个互联网，可以使用 Tailscale 或 Caddy 这类支持不暴露公网即可签发 HTTPS 证书的服务。

第二步：配置 Actual 使用证书

证书到手后有两种配置方式，二选一。

方式一：config.json

在运行 Actual Sync Server 的同一目录创建config.json（从源码构建时该目录是packages/sync-server/），把.key和.crt的路径写入：

{ "https": { "key": "/data/selfhost.key", "cert": "/data/selfhost.crt" } }

注意：如果使用 Docker 或类似容器环境，路径必须对容器可访问。Docker 容器中该目录是/data；如果你给容器挂载了卷，就把config.json放到宿主机上挂载/data的那个目录。上面的示例路径就是按 Docker 场景写的，非 Docker 场景请替换为你的实际文件路径。

方式二：环境变量

不方便新建文件时，可以用环境变量：把ACTUAL_HTTPS_KEY和ACTUAL_HTTPS_CERT分别设置为.key和.crt文件的内容。如果环境变量的值无法包含换行符，可以换行用\n代替，Actual 会自动转换回换行。

两个可选分支

• Docker + 自签名证书：健康检查可能不信任自签名证书，需要在 docker-compose.yml 的健康检查命令中加环境变量：

  test: [ 'CMD-SHELL', 'NODE_EXTRA_CA_CERTS=/data/selfhost.crt node src/scripts/health-check.js', ]

• 桌面客户端连接自签名服务器：在桌面应用的Where's the server?界面输入服务器 URL 后，若弹出提示选择证书的错误，选择对应证书重试即可。如果证书是用 mkcert 生成的，要指定的是根 CA 证书而不是服务器证书：运行mkcert -CAROOT找到根证书目录，把其中的rootCA.pem指定给桌面应用。

第三步：保证 COEP / COOP 两个请求头

• 使用默认actual-server包作为服务器：文档说明这些头始终自动启用，你不需要做任何事。

• 使用其他服务器：必须自行确认响应中带了Cross-Origin-Embedder-Policy: require-corp和Cross-Origin-Opener-Policy: same-origin。

• 在前面挂了 Nginx 之类的反向代理：这是最容易出问题的组合。应用本身会尝试自动设置这两个头，代理又手动设置一遍，就会产生重复头（例如require-corp, require-corp）。现代浏览器在头重复时会判安全策略无效，最终表现为SharedArrayBufferMissing致命错误。官方给出的解法是用proxy_hide_header先剥掉上游的头，再显式添加，让代理成为唯一的头来源：

  location / { proxy_pass http://actual_server:5006; # Prevents header duplication between Upstream and Proxy proxy_hide_header Cross-Origin-Embedder-Policy; proxy_hide_header Cross-Origin-Opener-Policy; # Explicitly set mandatory security headers add_header Cross-Origin-Embedder-Policy "require-corp" always; add_header Cross-Origin-Opener-Policy "same-origin" always; add_header Origin-Agent-Cluster "?1" always; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

  文档中的完整 Nginx 示例还包含server_name和 Let's Encrypt 证书路径（ssl_certificate/ssl_certificate_key）等，需要按你自己的域名和证书位置调整。Caddy（自动签发并续期 SSL）、Traefik、Apache httpd、Ngrok 的完整示例见 Using a Reverse Proxy；这些配置文档标注为"基础配置建议"，实际使用还需为所选工具启用额外的安全机制。

第四步：验证 HTTPS 与 SharedArrayBuffer

文档给出的测试方式是：配置完成后，确认自己使用的是https协议去访问你的实例。建议重新输入一遍服务器 URL，或开一个新标签页/新窗口，而不是在有错误的页面上直接刷新。

结合两份文档，可以按现象判断问题出在哪一环：

• 页面报SharedArrayBufferMissing：按 Using a Reverse Proxy 中的 Nginx 一节，先检查响应里是否存在重复的 COEP/COOP 头（如require-corp, require-corp），用proxy_hide_header方案去重。
• 浏览器直接提示证书无效：说明走了自签名证书路线（预期内的警告），或证书没有被客户端信任（桌面客户端场景见上文可选分支）。
• 头都正确但页面仍不可用：检查浏览器是否足够新，较新版本的 Chrome、Firefox、Safari、Edge 都支持SharedArrayBuffer；文档建议查阅 Can I Use 站点确认你使用的具体浏览器版本是否支持该特性。

参考资料：

• Enabling SharedArrayBuffer Access——三个条件的原始出处；
• Activating HTTPS——证书获取、config.json 与环境变量配置、测试步骤；
• Using a Reverse Proxy——反向代理下重复头问题的处理与各代理示例。

【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual