Actual Budget 从源码构建服务器全指南：环境准备、编译、运行与 systemd 开机自启

Actual Budget 从源码构建服务器全指南：环境准备、编译、运行与 systemd 开机自启

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

本指南面向希望通过编译源码的方式自建 Actual Budget 同步服务器的开发者与贡献者。文中将完整走通“前置环境 → 克隆仓库 → 安装依赖 → 构建 → 启动 → 首次访问 → systemd 守护 → 版本更新 → 多语言”的全流程，并结合本仓库（Actual 官方 monorepo）的真实构建脚本、启动链路与配置源码，说明每一步背后的原理，帮助你拥有一个可长期运行、可维护的本地优先个人财务服务器。

适用范围与更简单的替代方案

Actual 是一个“本地优先”（local-first）的个人财务应用，整个项目由客户端与服务器两部分组成。服务器负责跨设备同步数据，并内置随附最新版 Actual Web 客户端（相关功能划分可参考 安装总览 中的特性对照表：预算、报表、导入导出等无需服务器，而跨设备同步、浏览器访问、银行同步、API 使用则依赖服务器）。

从源码构建属于高度技术化的安装方式，官方文档明确推荐该路径主要面向贡献者。如果你只是想稳定地使用 Actual，官方更建议优先选择下列更简单的替代方案：

• PikaPods 托管：无需命令行，付费云端托管；
• 桌面客户端：下载即用的桌面应用；
• Server CLI：通过 npm 全局包一条命令启动服务器；
• Docker：使用官方镜像容器化部署。

如果你打算参与 Actual 的源码开发，或者希望完全掌控构建过程，那么请继续往下看。

前置条件（Prerequisites）

在开始之前，需要准备以下工具链：

Node.js v22 及以上

Actual 服务器要求Node.js v22 或更高版本（本仓库根目录 package.json 的engines字段实际声明为node: ">=22.18.0"）。建议从 Node.js 官网下载LTS版本。

• Windows 用户特别注意：安装 Node.js 时，务必在Tools for Native Modules页面勾选Automatically install the necessary tools。这是因为 Actual 依赖better-sqlite3等原生模块（见 packages/sync-server/package.json 的依赖列表），需要本机编译工具链。如果安装时错过了该选项，可以双击C:\Program Files\nodejs\install_tools.bat，或在终端中手动运行它。
• 建议使用版本管理工具（如nvm、asdf）在同一台机器上维护多个 Node.js 版本，便于切换。

Git

你需要安装 Git；Windows 用户建议同时安装Git Bash，以便在类 Unix 风格的 shell 中执行下面的命令。

Yarn

Actual 使用 Yarn 管理依赖（当前仓库为 Yarn 4 工作区 monorepo，根 package.json 中packageManager为yarn@4.17.1，engines.yarn为^4.9.1）。通过 npm 全局安装：

npm install --global yarn

安装 Actual：克隆、装依赖、构建

在满足全部前置条件后，打开 bash，在计划安装 Actual 的目录中执行以下步骤：

1. 克隆仓库

git clone https://gitcode.com/GitHub_Trending/ac/actual.git

2. 进入项目目录

cd actual

3. 安装全部依赖

yarn install

该命令会为 monorepo 中所有 workspace（packages/*，包括 API、CLI、桌面客户端、同步服务器、CRDT、组件库等）安装依赖。因为涉及better-sqlite3、argon2、bcrypt等原生模块，首次安装可能需要较长时间，Windows 上依赖前文提到的编译工具链。

4. 构建服务器

yarn build:server

这条命令并不是简单的单一构建。查看根 package.json 中的脚本定义可以发现，build:server实际等价于：

yarn build:browser && yarn workspace @actual-app/sync-server build

即先构建浏览器端 Web 客户端（./bin/package-browser），再构建@actual-app/sync-server工作区（内部执行vite build）。这一点很关键：同步服务器构建产物中内嵌了最新版的 Actual Web 前端，服务器启动后即可直接提供网页版界面。

从源码角度看，bin/package-browser 脚本还承担了一项额外工作：当packages/desktop-client/locale目录不存在时，它会自动克隆翻译仓库到该位置，随后执行lage build:browser --to=@actual-app/web。也就是说，只要网络可达，构建过程会顺带准备好多语言资源（下文“多语言”一节还会详细说明）。

运行 Actual 服务器

安装并构建完成后，启动服务器：

yarn start:server

注意：重启电脑后需要再次执行该命令才能重新启动服务器（除非你配置了下文介绍的 systemd 开机自启）。

启动链路与默认行为（源码视角）

yarn start:server等价于yarn workspace @actual-app/sync-server start，而 packages/sync-server/package.json 中该脚本定义为yarn build && node build/app.js。因此每次启动都会先增量构建，再运行入口程序。

入口程序 packages/sync-server/app.ts 的逻辑是：先执行数据库迁移（runMigrations()），迁移成功后才动态导入 packages/sync-server/src/app.ts 并调用其run()。也就是说，启动顺序被刻意设计为先迁移、再起服务，避免表结构未就绪时请求报错。

默认配置下（详见 packages/sync-server/src/load-config.js 中的 convict 配置 schema）：

• 监听端口5006（可通过ACTUAL_PORT或config.json的port覆盖）；
• 监听地址::，多数操作系统上同时覆盖 IPv4 与 IPv6（可通过ACTUAL_HOSTNAME覆盖）；
• 数据目录默认取ACTUAL_DATA_DIR环境变量；若未设置，优先使用/data目录（存在时），否则使用项目根目录，预算数据与服务器元数据分别存放在user-files/与server-files/子目录；
• 非开发环境下启用请求限流（每 60 秒最多 500 个请求），并设置 CSP、COOP/COEP等安全响应头（SharedArrayBuffer依赖这些头启用，这是 SQLite 引擎在浏览器侧正常运行的前提）。

服务器还暴露了几个便于运维的 HTTP 端点（见 packages/sync-server/src/app.ts）：

• GET /health→ 返回{"status":"UP"}，适合做存活探针；
• GET /info→ 返回构建版本信息；
• GET /metrics→ 返回进程内存与运行时长；
• GET /mode→ 返回应用模式。

首次访问与初始配置

服务器启动后，在浏览器中访问：

http://localhost:5006

首次访问时，界面可能提示你提供服务器 URL。对于本地安装，直接点击Use localhost:5006按钮，即可连接到你刚刚构建并启动的这台服务器。

服务器运行之后，你可以通过配置文件或环境变量调整它的行为——例如数据目录、上传大小限制、登录方式、HTTPS、OpenID 等，完整说明见服务器配置文档。从 load-config.js 的加载逻辑看，配置优先级为：环境变量 >config.json> 默认值，其中config.json的查找顺序是ACTUAL_CONFIG_PATH指定路径 → 项目根目录config.json→ 数据目录config.json。

Linux 下使用 systemd 实现开机自启

如果你希望 Actual 服务器随系统启动而自动运行，可以在 Linux 上配置一个 systemd 单元文件。以下操作需要 root 权限（打开 root 终端会话，或在每条命令前加sudo）。

1. 创建单元文件

用你喜欢的编辑器创建服务单元文件，例如：

vi /etc/systemd/system/actual-server.service

内容如下（注意将WorkingDirectory改成你的 Actual 安装目录，例如/var/www/html/actual）：

[Unit] Description=Actual-Server (https://actualbudget.org) After=network.target [Service] WorkingDirectory=[Link to your actual-server install directory, ex. /var/www/html/actual] ExecStart=/usr/bin/yarn start:server Restart=on-watchdog [Install] WantedBy=multi-user.target

提示：官方文档示例中同时出现了/etc/systemd/service/与/etc/systemd/system/两种写法，前者疑为笔误；systemd 单元文件的常规存放目录是/etc/systemd/system/，后续systemctl enable引用的也是该路径，实际部署时请统一放在/etc/systemd/system/下。

2. 让 systemd 重新扫描单元文件

systemctl daemon-reload

3. 安装并启动服务

systemctl enable --now /etc/systemd/system/multi-user.target.wants/actual-server.service

4. 确认服务器运行状态

systemctl status actual-server

正常输出类似：

root@server:/etc/systemd/system# systemctl status actual-server ● actual-server.service - Actual-Server (https://actualbudget.org) Loaded: loaded (/lib/systemd/system/actual-server.service; enabled; vendor pres> Active: active (running) since Mon 2024-11-18 14:58:29 EST; 23h ago Main PID: 842857 (node) Tasks: 33 (limit: 38316) Memory: 45.9M CPU: 1.995s CGroup: /system.slice/actual-server.service ├─842857 node /usr/bin/yarn start:server ├─842870 /usr/bin/node /var/www/html/actual-server/.yarn/releases/yarn-> └─842881 /usr/bin/node app

检查的重点是Active: active (running)这一段，它表示服务正在运行。从进程树可以看到实际是 yarn 拉起 Node 再启动app进程的完整链条。

5. 日常运维命令

• 停止：systemctl stop actual-server
• 启动：systemctl start actual-server
• 重启：systemctl restart actual-server
• 查看日志 / 排错：systemctl status actual-server

6. 对外暴露与安全加固

如果你的服务器需要暴露到公网，建议在它前面配置带 SSL 的反向代理，而不是直接开放端口。仓库中提供了 Caddy、Traefik、Nginx、Apache、Ngrok 等反向代理配置示例，以及激活 HTTPS 的完整步骤（自签名证书、mkcert、Tailscale/Caddy 免公网签发等方案）。另外注意：Nginx 场景下要正确处理COOP/COEP头，避免因重复头导致SharedArrayBufferMissing致命错误，具体配置同样见反向代理文档。

更新 Actual

Actual 功能迭代频繁，官方建议本地安装始终跟随最新版本（发布记录见 releases）。更新步骤：

1. 若服务器正在运行，先停止它：按Ctrl-C（macOS 同样适用），或直接关闭运行它的终端窗口。
2. 在克隆目录中拉取最新代码：

   git pull

3. 更新依赖：

   yarn install

4. 用最新代码重新构建服务器：

   yarn build:server

5. 重新启动服务器：

   yarn start:server

多语言支持（Translations）

如果你希望 Actual 显示英文以外的语言，需要额外准备翻译资源。有两种方式：

方式一：跟随官方构建流程（推荐）

如上文所述，bin/package-browser 在构建 Web 客户端时会自动检查packages/desktop-client/locale目录，若不存在则自动克隆翻译仓库并拉取最新翻译。因此只要你按本文的yarn build:server流程构建，多语言资源通常已被一并就绪。

方式二：手动配置

如果你在构建时跳过了翻译步骤，或希望手动管理，可以执行：

cd actual # 项目根目录 cd packages/desktop-client # 进入桌面客户端工作区 git clone <translations-repo> locale

即把翻译仓库克隆为packages/desktop-client/locale目录。Actual 使用 i18next 框架进行国际化，翻译相关的开发规范可参考 i18n 文档（注意：该项目不接受直接修改翻译文件的 Pull Request，翻译工作通过 Weblate 平台协作完成）。

常见问题与排错思路

以下问题与对策多可从仓库源码中得到印证：

• 原生模块编译失败（尤其 Windows）：better-sqlite3、argon2、bcrypt属于需要本地编译的原生依赖。请确认 Node.js 安装时勾选了“自动安装必要工具”，或运行C:\Program Files\nodejs\install_tools.bat补装编译链。
• 端口被占用 / 服务起不来：默认端口为 5006。可通过环境变量ACTUAL_PORT或config.json中的port修改；监听地址可用ACTUAL_HOSTNAME调整。
• 配置不生效：配置优先级为环境变量 >config.json> 默认值，且环境变量名与config.json键名并非一一对应（例如https配置对应的环境变量是ACTUAL_HTTPS_KEY/ACTUAL_HTTPS_CERT）。建议直接查阅 load-config.js 中的完整 schema 核对键名，并参考服务器排错文档开启 debug 日志定位问题。
• 想以开发模式运行：可执行yarn start:server-dev，此时NODE_ENV=development，服务器会把前端路由代理到localhost:3001的 Vite 开发服务器，支持热更新（相关逻辑见 packages/sync-server/src/app.ts 中的开发分支）；该模式主要面向 Actual 本身的开发调试。
• 生产环境精简依赖：如果只为运行同步服务器，可以用yarn install:server（即yarn workspaces focus @actual-app/sync-server --production）只安装服务器运行所需的依赖，减少磁盘占用。

至此，你已经从零完成了一次 Actual Budget 服务器的源码构建与部署。这套流程不仅是日常自建服务器的基础，也是深入参与 Actual 开发（阅读构建脚本、启动链路、配置 schema 等）的良好起点；完整的开发环境搭建（含 Dev Container、Docker Compose、类型检查与测试命令）可进一步参考开发环境设置文档。

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