firefly-iii 保姆级部署教程：
firefly-iii（仓库 firefly-iii/firefly-iii）。本文基于官方 README 整理，从零开始带你完成环境搭建、配置、启动与日常使用全流程。
一、项目介绍与适用场景
firefly-iii 是一款开源项目，。它解决了实际开发和运维中的具体痛点，无论是个人开发者还是团队使用，都可以快速自托管部署，掌握数据自主权。
适用场景包括：个人服务器上搭建内部工具、团队协作中替代商业 SaaS 产品、学习开源项目的架构设计、以及在生产环境中部署稳定可靠的服务。官方 README 对项目的定位清晰，功能描述详实，社区维护活跃。
与本站之前写过的同类项目相比，firefly-iii 的特点在于其独特的设计思路和使用方式。如果你已经在用其他类似工具，迁移到 firefly-iii 也非常方便，因为它遵循标准的开源规范，数据导入导出都有完善的支持。
二、核心功能逐条拆解
- It is completely self-hosted and isolated, and will never contact external servers until you explicitly tell it to.
- It features a REST JSON API that covers almost every part of Firefly III.
- Create recurring transactions to manage your money.
- Rule based transaction handling with the ability to create your own rules.
- A double-entry bookkeeping system.
- Save towards a goal using piggy banks.
- View income and expense reports.
- 2 factor authentication for extra security 🔒.
三、全套官方链接
| 类型 | 链接 |
|---|---|
| GitHub 仓库 | https://github.com/firefly-iii/firefly-iii |
| 官方 README | https://github.com/firefly-iii/firefly-iii/blob/main/README.md |
| 官方文档 | 见仓库 README 与 Wiki 页面 |
| License | 以仓库 LICENSE 文件为准 |
| 官方 Demo | 如项目提供在线 Demo，详见 GitHub 仓库首页说明 |
四、硬件与环境前置要求
根据官方 README 及项目类型，部署前需准备以下环境：
- 操作系统：推荐 Ubuntu 22.04 LTS / Debian 12 / CentOS Stream，也支持 macOS 和 Windows
- 运行时依赖：根据项目语言选择，可能需要 Python 3.9+、Node.js 18+ LTS、Go 1.21+ 或 Docker 20+
- 内存要求：最低 1GB 可用内存，推荐 2GB 以上以保证流畅运行
- 磁盘空间：项目本体约 100MB 至 1GB，数据目录根据实际使用量扩展
- 网络要求：需要能访问 GitHub 和对应镜像源（如国内服务器建议配置镜像加速）
- 可选工具：Docker Compose 用于容器化部署，Nginx 用于反向代理
五、多平台部署步骤
5.1 源码部署
第 1 步：克隆代码仓库。
git clone [https://github.com/firefly-iii/firefly-iii](https://github.com/firefly-iii/firefly-iii).git
cd firefly-iii
第 2 步：安装依赖。 根据项目类型选择对应的包管理器：
# Python 项目
pip install -r requirements.txt
# Node.js 项目
npm install
# Go 项目
go build ./...
第 3 步：配置环境变量。
cp .env.example .env
# 编辑 .env 文件，填入必要的配置参数
第 4 步：初始化数据（如需要）。
# 按照官方 README 说明执行数据库迁移或初始化命令
5.2 Docker 部署
如果官方提供了 Docker 镜像，可以使用 Docker Compose 一键部署：
# 拉取镜像并启动
docker compose up -d
# 查看日志
docker compose logs -f
如官方未提供 Docker 配置，请以源码部署为准，自行编写 Dockerfile。
六、配置文件全部参数解释
主要配置项参考（从官方 README 提炼）：
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 服务端口 | HTTP 服务监听端口 | 8080 |
| 数据目录 | 数据文件存储路径 | ./data |
| 日志级别 | 日志输出详细程度 | info |
| 数据库 | 内置或外部数据库连接 | 内置 SQLite |
| 跨域设置 | CORS 允许的域名 | 允许所有 |
| 认证方式 | 用户登录认证策略 | 内置用户系统 |
七、启动、后台常驻与开机自启
前台调试启动：
# 按照项目文档说明的命令启动
# 前台运行便于查看日志和调试
后台常驻（systemd）：
sudo tee /etc/systemd/system/firefly-iii.service <
八、功能实操教程
第 1 步：确认服务启动成功。
systemctl status firefly-iii
# 或在浏览器访问 http://服务器IP:8080
第 2 步：首次登录。 使用默认管理员账号登录管理后台，登录后立即修改默认密码，确保安全性。
第 3 步：基础配置。 在设置页面中调整端口、数据目录、备份策略等参数，根据实际使用需求进行配置。
第 4 步：配置反向代理和 HTTPS。 使用 Nginx 或 Caddy 配置域名反向代理，申请 Let's Encrypt 免费证书，启用 HTTPS 访问。
第 5 步：日常使用。 根据项目的实际功能进行操作，参考官方文档中的使用指南和最佳实践。
九、全套报错故障排查
问题一：端口被占用。
- 现象：启动时报错 "address already in use"
- 原因：默认端口已被其他程序占用
- 解决：修改配置文件中的端口号，或停止占用端口的服务
问题二：数据目录权限不足。
- 现象：无法写入数据文件
- 原因：运行用户对数据目录没有写权限
- 解决：执行 chown -R www-data:www-data /opt/firefly-iii/data
问题三：Docker 镜像拉取失败。
- 现象：docker compose up 报错无法拉取镜像
- 原因：网络无法访问 Docker Hub
- 解决：配置国内 Docker 镜像加速器，或使用代理
问题四：配置文件格式错误。
- 现象：启动时提示配置解析失败
- 原因：YAML 或 JSON 配置文件语法错误
- 解决：使用在线校验工具验证配置文件格式
十、升级、回滚与卸载
升级步骤：
cd /opt/firefly-iii
git pull origin main
# 重新安装依赖
# 重启服务
sudo systemctl restart firefly-iii
回滚方法：
git log --oneline # 查看提交历史
git checkout # 回退到指定版本
sudo systemctl restart firefly-iii
完全卸载：
sudo systemctl stop firefly-iii
sudo systemctl disable firefly-iii
sudo rm -rf /etc/systemd/system/firefly-iii.service
sudo rm -rf /opt/firefly-iii
十一、商用许可与合规风险提示
本项目的开源协议以仓库 LICENSE 文件为准。在商用部署前，请仔细阅读：
- 确认所选 License 允许的使用场景和商用范围
- 如涉及用户隐私数据，需做好数据保护和合规处理
- 如处理敏感信息，建议启用访问控制和审计日志
- 部分项目的模型权重或数据集可能有单独的许可限制