从零到一：Firefly III 私有化部署与移动端适配实战

1. 为什么选择Firefly III搭建个人财务系统

记账这件事，说大不大说小不小。从学生时代用Excel手工记录生活费，到后来用各种手机APP自动同步账单，我几乎试遍了市面上所有主流记账工具。直到三年前发现银行账单出现莫名扣款，才意识到把财务数据完全交给第三方服务的风险。Firefly III正是在这种需求下进入我的视线——它像财务版的WordPress，给你完全的数据掌控权。

这个开源项目用Laravel框架开发，最吸引我的是它的"三无"特性：无云服务依赖、无数据上报、无商业套路。所有交易记录都存放在自己的服务器上，连报表生成都在本地完成。实测下来，单月3000+条交易记录的统计分析响应速度保持在2秒内，比某些付费软件还流畅。对于技术爱好者来说，它的Docker化部署更是省心，我在老款群晖DS218+上跑起来毫无压力。

移动端适配是很多人关心的重点。虽然官方没有原生APP，但通过PWA技术实现的Web应用体验相当不错。我的小米手机将网页添加到桌面后，图标和启动动画与原生APP几乎无异。更惊喜的是发现第三方开发者基于API做了几个客户端，后文会详细对比Android平台的Photuris III和Firefly Personal Finance的实际体验。

2. 部署前的准备工作

2.1 硬件与网络环境配置

我的部署环境是一台闲置的群晖DS218+，2GB内存完全够用。建议准备：

  • 至少1GHz双核CPU
  • 2GB以上内存
  • 10GB存储空间（长期使用建议50GB+）

数据库选择上，MariaDB 10.3和MySQL 5.7都经过实测兼容。有个坑要注意：某些ARM架构NAS（如树莓派）需要手动编译PHP扩展，建议x86设备省心。网络方面确保3306（MySQL）和8080（Web）端口可用，我在路由器上做了DDNS解析方便外网访问。

2.2 数据库初始化

先用phpMyAdmin创建专用账户更安全：

CREATE DATABASE firefly CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; GRANT ALL PRIVILEGES ON firefly.* TO 'firefly'@'%' IDENTIFIED BY '你的强密码'; FLUSH PRIVILEGES;

这里有个细节：一定要用utf8mb4字符集，否则中文备注会乱码。我曾因为偷懒用默认的latin1导致三个月数据需要重导，血泪教训。

3. Docker化部署实战

3.1 容器配置详解

在群晖Docker注册表搜索fireflyiii/core时，注意避开已弃用的jc5x镜像。我的docker-compose.yml配置如下：

version: '3' services: firefly: image: fireflyiii/core:latest ports: - "8888:8080" volumes: - /volume1/docker/firefly/upload:/var/www/html/storage/upload - /volume1/docker/firefly/export:/var/www/html/storage/export environment: APP_KEY: '32位随机字符串' # 可用openssl rand -base64 24生成 DB_HOST: '192.168.1.100' DB_PORT: '3306' DB_CONNECTION: 'mysql' DB_DATABASE: 'firefly' DB_USERNAME: 'firefly' DB_PASSWORD: '你的数据库密码'

重点说下APP_KEY：它相当于应用加密盐值，首次启动后修改会导致所有用户会话失效。建议在SSH里用openssl rand -base64 24 | head -c 32生成真随机数。

3.2 首次启动的常见问题

日志中出现"NOTICE: ready to handle connections"才算成功。我遇到过的典型错误：

  1. 数据库连接超时：检查DB_HOST是否用了容器名而非IP
  2. 权限不足：给upload/export目录chmod -R 775权限
  3. 时区不对：在环境变量加TZ=Asia/Shanghai

启动成功后用http://NAS_IP:8888访问，注册时密码必须16位以上。建议用Bitwarden生成并保存，因为后续API调用都要用这个密码。

4. 移动端适配全攻略

4.1 PWA网页版优化技巧

在手机Chrome打开Web界面后，点击"添加到主屏幕"，会发现图标是默认的PHP齿轮LOGO。要自定义图标需要修改nginx配置：

location / { # 添加PWA支持 add_header Service-Worker-Allowed /; try_files $uri $uri/ /index.php?$query_string; }

然后准备192x192和512x512的PNG图标，通过后台"系统设置→自定义LOGO"上传。实测华为EMUI和MIUI都能完美显示桌面图标，且支持指纹验证登录。

4.2 第三方客户端对比

Android平台两款APP我都深度使用过：

  1. Photuris III：界面最接近网页版，但2022年后停止更新，偶尔闪退
  2. Firefly Personal Finance：Material Design风格，支持生物识别，但报表功能残缺

获取API令牌时有个技巧：在"个人档案→OAuth授权"创建令牌后，立即用Postman测试接口：

GET http://你的域名/api/v1/about Authorization: Bearer 你的令牌

返回200状态码才算配置成功。iOS用户可以用Shortcuts实现快速记账，GitHub上有现成的模板可以直接导入。

5. 中文场景下的特殊配置

5.1 货币与语言设置

首次登录后要立即修改：

  1. 在"账户→创建账户"里将默认货币改为人民币
  2. 系统设置→语言选"简体中文"
  3. 时区设置为Asia/Shanghai

有个隐藏设置：在.env文件加FF_LOCALE=zh_CN可以修复日期显示格式问题。导入支付宝账单时，记得在CSV导入界面选择"Alipay"预设格式，否则分类映射会错乱。

5.2 自动记账方案

通过IFTTT+Email解析实现自动化：

  1. 在Firefly开启SMTP设置
  2. 配置邮箱规则：收到银行短信后转发到特定地址
  3. 用Python脚本解析金额和商户：
import re from datetime import datetime def parse_sms(text): pattern = r'支出(\d+\.\d+)元.*?(麦当劳|美团)' match = re.search(pattern, text) if match: return { 'amount': match.group(1), 'payee': match.group(2), 'date': datetime.now().strftime('%Y-%m-%d') }

虽然要写些规则，但实现后能节省90%的记账时间。我的外卖和打车消费现在都是自动归类，月底报表一目了然。

6. 数据备份与迁移策略

6.1 定期备份方案

除了常规的数据库dump，还要注意：

# 导出交易数据 docker exec -it fireflyiii php artisan firefly:export /var/www/html/storage/export/backup.json # 备份上传文件 tar -czvf uploads.tar.gz /volume1/docker/firefly/upload/

建议写个cron任务每周自动备份到异地存储。我用的rclone同步到加密的WebDAV，命令如下：

rclone copy /backup firefly:backup --password-file=/etc/rclone.pass

6.2 跨设备同步方案

通过Tailscale组建虚拟局域网：

  1. 在NAS和手机安装Tailscale
  2. 启用子网路由功能
  3. 手机客户端直接连接内网地址

这样无论在家还是外出，都能用https://firefly.tailnet:8888访问，数据完全不经过第三方服务器。实测地铁里刷报表的加载速度在3秒以内，和局域网体验无异。