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你需要安装 GitWindows 用户建议同时安装Git Bash以便在类 Unix 风格的 shell 中执行下面的命令。YarnActual 使用 Yarn 管理依赖当前仓库为 Yarn 4 工作区 monorepo根 package.json 中packageManager为yarn4.17.1engines.yarn为^4.9.1。通过 npm 全局安装npm install --global yarn安装 Actual克隆、装依赖、构建在满足全部前置条件后打开 bash在计划安装 Actual 的目录中执行以下步骤1. 克隆仓库git clone https://gitcode.com/GitHub_Trending/ac/actual.git2. 进入项目目录cd actual3. 安装全部依赖yarn install该命令会为 monorepo 中所有 workspacepackages/*包括 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 --toactual-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.tsGET /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] DescriptionActual-Server (https://actualbudget.org) Afternetwork.target [Service] WorkingDirectory[Link to your actual-server install directory, ex. /var/www/html/actual] ExecStart/usr/bin/yarn start:server Restarton-watchdog [Install] WantedBymulti-user.target提示官方文档示例中同时出现了/etc/systemd/service/与/etc/systemd/system/两种写法前者疑为笔误systemd 单元文件的常规存放目录是/etc/systemd/system/后续systemctl enable引用的也是该路径实际部署时请统一放在/etc/systemd/system/下。2. 让 systemd 重新扫描单元文件systemctl daemon-reload3. 安装并启动服务systemctl enable --now /etc/systemd/system/multi-user.target.wants/actual-server.service4. 确认服务器运行状态systemctl status actual-server正常输出类似rootserver:/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-server6. 对外暴露与安全加固如果你的服务器需要暴露到公网建议在它前面配置带 SSL 的反向代理而不是直接开放端口。仓库中提供了 Caddy、Traefik、Nginx、Apache、Ngrok 等反向代理配置示例以及激活 HTTPS 的完整步骤自签名证书、mkcert、Tailscale/Caddy 免公网签发等方案。另外注意Nginx 场景下要正确处理COOP/COEP头避免因重复头导致SharedArrayBufferMissing致命错误具体配置同样见反向代理文档。更新 ActualActual 功能迭代频繁官方建议本地安装始终跟随最新版本发布记录见 releases。更新步骤若服务器正在运行先停止它按Ctrl-CmacOS 同样适用或直接关闭运行它的终端窗口。在克隆目录中拉取最新代码git pull更新依赖yarn install用最新代码重新构建服务器yarn build:server重新启动服务器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 平台协作完成。常见问题与排错思路以下问题与对策多可从仓库源码中得到印证原生模块编译失败尤其 Windowsbetter-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_ENVdevelopment服务器会把前端路由代理到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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考