[实操] 基于Firefly-III搭建个人财务管理系统

摘要

Firefly III 是一款开源的个人财务管理系统，允许用户追踪和管理个人或家庭的财务状况。通过使用 Docker 和 Docker Compose，我们可以轻松地在任何支持 Docker 的平台上部署 Firefly III。本文将记录如何使用 Docker Compose 快速部署 Firefly III 个人财务管理系统。

前言

我一直有记账的习惯，最早是从用笔记本记录开始的，后来改用了Excel表格。不管是哪种方式，目的都是为了能更好地规划消费和理财。不过，随着时间推移，尤其是工作后收入和支出变得频繁起来，这些传统方式逐渐显现出不便之处；数据不够直观难以进行复盘，每年到底收入多少、花了多少，常常无法一目了然。

市场上虽然有不少记账软件，但大多数只是流水账式的记录，和传统方法相比也仅仅是手机终端比较方便罢了，数据安全也让我有点担心，毕竟谁也不想自己的财务信息随便被别人看到。因此，要么本地记录，要么私有化搭建一个属于自己的财务管理系统。

在探索过程中，我发现 Firefly III 非常符合我的需求。它采用了复式记账法，能够更准确地反映财务状况和收支情况，帮助我更好地理解和管理个人财务。此外，Firefly III 生态还提供了手机移动端应用，随时随地都能记账也很方便。更重要的是，作为一个开源项目，Firefly III 允许我完全掌控自己的数据，确保数据的安全性和隐私性。

 
开源项目地址：Firefly III

更多帮助信息： Firefly III 官方指南
 

前置条件

在开始之前，请确保您的系统已经安装了以下软件：

• Docker
• Docker Compose
• 可访问Docker Hub （用于拉取官方镜像）
• MySQL数据库 （可选，或可以直接构建数据库）

步骤 1: 创建项目目录

首先，在您的服务器或本地机器上选择一个合适的位置创建一个新的文件夹作为项目的根目录。例如：

mkdir ~/firefly-iii
cd ~/firefly-iii
# 目录下分别创建 .env、docker-compose.yml

步骤 2: 编写 .env 文件

.env 文件用于定义环境变量，对于运行 Firefly III 至关重要。根据实际需求填写参数值(必改内容已特别注释)，并保存为 .env 文件：

# 你可以将此保留为 "local"。如果你将其更改为 "production"，大多数控制台命令将要求额外确认。
# 永远不要将其设置为 "testing"。
APP_ENV=production

# 如果你想在错误屏幕上看到调试信息，请将其设置为 true。
APP_DEBUG=true

# 这应该是你的电子邮件地址。
# 如果你使用 Docker 或类似工具，可以通过使用 SITE_OWNER_FILE 从文件设置此变量
# 该变量用于向非管理员用户显示的一些错误中。
SITE_OWNER=mail@example.com

# 会话的加密密钥。请确保其非常安全。
# 将其更改为正好 32 个字符的字符串或使用类似 `php artisan key:generate` 的命令生成它。
# 如果你使用 Docker 或类似工具，可以通过使用 APP_KEY_FILE 从文件设置此变量
#
# 避免在 APP_KEY 中使用 "#" 字符，它可能会导致问题。
#
APP_KEY=xcdJSxxxxxxxxxxxxxxptL4U3qgC            # <-- 替换为实际的 APP_KEY

# Firefly III 将使用此语言启动（对于新用户和未认证的访客）
# 可用语言列表：https://github.com/firefly-iii/firefly-iii/tree/main/resources/lang
#
# 如果文本仍然是英文，请记住并非所有内容都已翻译。
DEFAULT_LANGUAGE=en_US

# 区域设置定义数字的格式。
# 默认情况下，此值与语言相同。
DEFAULT_LOCALE=equal

# 将此值更改为你的首选时区。
# 示例：Europe/Amsterdam
# 支持的时区列表，请参见 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
TZ=Asia/Shanghai                              # <-- 默认欧洲，已改上海

# TRUSTED_PROXIES 在使用 Docker 和/或反向代理时很有用。
# 设置为 ** 反向代理即可正常工作。
TRUSTED_PROXIES=**                             # ** 是一个特殊的值，表示信任所有代理服务器，默认为空，使用反代则填写

# 日志通道定义日志条目发送的位置。
# 其他选项也存在。你可以使用 'single' 用于一个大的错误日志（不推荐）。
# 还有 'syslog'，'errorlog' 和 'stdout' 可以记录到系统本身。
# 旋转日志选项 'daily' 创建 5 个文件（惊喜！）它们会轮换。
# 冷酷的选项是 'papertrail' 用于云日志记录
# 默认设置 'stack' 将同时记录到 'daily' 和 'stdout'。
LOG_CHANNEL=stack

# 日志级别。你可以从最不严重到最严重设置：
# debug, info, notice, warning, error, critical, alert, emergency
# 如果将其设置为 debug，你的日志将变得庞大且增长迅速。如果你将其设置为 emergency
# 可能根本不会记录任何内容。
APP_LOG_LEVEL=notice

# 审计日志级别。
# 审计日志用于记录 Firefly III 的重要事件到单独的通道。
# 这些日志条目可能包含敏感的财务信息。
# 默认情况下禁用审计日志。
#
# 要启用它，请将 AUDIT_LOG_LEVEL 设置为 "info"
# 要禁用它，请将 AUDIT_LOG_LEVEL 设置为 "emergency"
AUDIT_LOG_LEVEL=emergency

#
# 如果愿意，你可以将审计日志重定向到另一个通道。
# 设置 'audit_stdout'，'audit_syslog'，'audit_errorlog' 记录到系统本身。
# 使用 audit_daily 记录到旋转文件。
# 使用 audit_papertrail 记录到 papertrail。
#
# 如果这样做，审计日志可能会与其他普通日志混合，因为这些通道
# 的设置通常与普通日志的设置相同。
AUDIT_LOG_CHANNEL=

#
# 用于记录到 papertrail：
# 也用于审计日志记录到 papertrail：
#
PAPERTRAIL_HOST=
PAPERTRAIL_PORT=

# 数据库凭据。请确保数据库存在。我建议为 Firefly III 使用专用用户
# 对于其他数据库类型，请参见常见问题解答：https://docs.firefly-iii.org/references/faq/install/#i-want-to-use-sqlite
# 如果你使用 Docker 或类似工具，可以通过附加 _FILE 来从文件设置这些变量
# 使用 "pgsql" 用于 PostgreSQL
# 使用 "mysql" 用于 MySQL 和 MariaDB。
# 使用 "sqlite" 用于 SQLite。
DB_CONNECTION=mysql
DB_HOST=172.17.0.9                        # <-- 替换为你的数据库主机
DB_PORT=3306                              # <-- 替换为你的数据库端口
DB_DATABASE=mysql_name                    # <-- 替换为你的数据库名称
DB_USERNAME=mysql_user                    # <-- 替换为你的 MySQL 用户名
DB_PASSWORD=mysql_password                # <-- 替换为你的 MySQL 密码
# 当不使用套接字连接时留空或省略
DB_SOCKET=

# MySQL 支持 SSL。你可以在下面配置它。
# 如果你使用 Docker 或类似工具，可以通过附加 _FILE 来从文件设置这些变量
MYSQL_USE_SSL=false
MYSQL_SSL_VERIFY_SERVER_CERT=false
# 你需要至少设置以下选项之一
MYSQL_SSL_CAPATH=/etc/ssl/certs/
MYSQL_SSL_CA=
MYSQL_SSL_CERT=
MYSQL_SSL_KEY=
MYSQL_SSL_CIPHER=

# PostgreSQL 支持 SSL。你可以在下面配置它。
# 如果你使用 Docker 或类似工具，可以通过附加 _FILE 来从文件设置这些变量
PGSQL_SSL_MODE=prefer
PGSQL_SSL_ROOT_CERT=null
PGSQL_SSL_CERT=null
PGSQL_SSL_KEY=null
PGSQL_SSL_CRL_FILE=null

# 对于 postgresql 15 及以上版本，将此设置为 public 将不再按预期工作，
# 因为 'public' 架构没有授予必要的权限。这可以通过具有超级用户权限的用户授予这些必要权限来解决，
# 但在安全意识强的设置中这是不可行的。
# 你需要将其设置为你想要使用的架构。
PGSQL_SCHEMA=public

# 如果你正在寻找性能改进，可以安装 memcached 或 redis
CACHE_DRIVER=file
SESSION_DRIVER=file

# 如果你将上述任一选项设置为 'redis'，你可能还需要更新这些设置
# 如果你使用 Docker 或类似工具，可以通过附加 _FILE 来从文件设置这些变量而不是从环境变量

# 可以是 tcp 或 unix。不支持 http
REDIS_SCHEME=tcp

# 仅在使用 'unix' 作为 REDIS_SCHEME 时使用。否则留空。
REDIS_PATH=

# 仅在使用 'tcp' 或 'http' 作为 REDIS_SCHEME 时使用。否则留空。
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# 仅在使用 Redis 6+ 并设置了适当的 ACL 时使用。否则留空。
REDIS_USERNAME=
REDIS_PASSWORD=

# 始终使用引号，并确保 redis 数据库 "0" 和 "1" 存在。否则相应更改。
REDIS_DB="0"
REDIS_CACHE_DB="1"

# Cookie 设置。通常不需要更改这些。
# 如果你使用 Docker 或类似工具，可以通过附加 _FILE 来从文件设置
# 而不是从环境变量
# 将 samesite 设置为 "strict" 可能会导致登录问题。
COOKIE_PATH="/"
COOKIE_DOMAIN=
COOKIE_SECURE=false
COOKIE_SAMESITE=lax

# 如果你希望 Firefly III 发送电子邮件，请更新这些设置
# 有关说明，请参见：https://docs.firefly-iii.org/how-to/firefly-iii/advanced/notifications/#email
# 如果你使用 Docker 或类似工具，可以通过附加 _FILE 来从文件设置这些变量而不是从环境变量
MAIL_MAILER=log
MAIL_HOST=null
MAIL_PORT=2525
MAIL_FROM=changeme@example.com
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_SENDMAIL_COMMAND=

# 其他邮件驱动程序：
# 如果你使用 Docker 或类似工具，可以通过附加 _FILE 来从文件设置这些变量而不是从环境变量
MAILGUN_DOMAIN=
MAILGUN_SECRET=

# 如果你在 mailgun 的 EU 区域，请使用 api.eu.mailgun.net，否则使用 api.mailgun.net
# 如果你使用 Docker 或类似工具，可以通过附加 _FILE 来从文件设置此变量而不是从环境变量
MAILGUN_ENDPOINT=api.mailgun.net

# 如果你使用 Docker 或类似工具，可以通过附加 _FILE 来从文件设置这些变量而不是从环境变量
MANDRILL_SECRET=
SPARKPOST_SECRET=
MAILERSEND_API_KEY=

# Firefly III 可以向你发送以下消息。
SEND_ERROR_MESSAGE=true

# 这些消息包含（敏感的）交易信息：
SEND_REPORT_JOURNALS=true

# 如果你希望设置某些事物的位置，如交易，请将此值设置为 true。
# 由于涉及外部服务，这是可选的，默认情况下处于禁用状态。
ENABLE_EXTERNAL_MAP=false

#
# 启用或禁用汇率转换功能。此功能尚未被 Firefly III 使用
#
ENABLE_EXCHANGE_RATES=false

# 将此值设置为 true 如果你希望 Firefly III 从互联网下载货币汇率
# 这些汇率由 Firefly III 的创建者托管在
# Azure 存储容器内。
# 并非所有货币都可用。汇率可能不准确。
ENABLE_EXTERNAL_RATES=false

# 地图默认位置为：
MAP_DEFAULT_LAT=31.241767               # <-- 这里已替换为上海坐标
MAP_DEFAULT_LONG=121.498885
MAP_DEFAULT_ZOOM=6

#
# 某些对象可以容纳一个 URL，例如交易和 Webhook。
# 默认情况下，允许以下协议：
# http, https, ftp, ftps, mailto
#
# 要更改此设置，请在此下方设置你偏好的逗号分隔集。
# 确保包含 http, https 和其他默认协议（如果需要）。
#
VALID_URL_PROTOCOLS=

#
# Firefly III 认证设置
#

#
# Firefly III 支持几种认证方法：
# - 'web'（默认，使用内置数据库）
# - 'remote_user_guard' 用于 Authelia 等
# 有关这些设置的更多信息，请参阅文档。
# https://docs.firefly-iii.org/how-to/firefly-iii/advanced/authentication/
#
# LDAP 已不再支持 :(
#
AUTHENTICATION_GUARD=web

#
# 远程用户守护程序设置
#
AUTHENTICATION_GUARD_HEADER=REMOTE_USER
AUTHENTICATION_GUARD_EMAIL=

#
# Firefly III 为你的 OAuth 令牌生成基本密钥对。
# 如果你愿意，可以使用自己的（安全）值覆盖密钥。
# 如果你使用 Docker 密钥或其他类似的解决方案进行密钥管理，
# 也可以设置 PASSPORT_PUBLIC_KEY_FILE 或 PASSPORT_PRIVATE_KEY_FILE
#
PASSPORT_PRIVATE_KEY=
PASSPORT_PUBLIC_KEY=

#
# 额外的认证设置
#
CUSTOM_LOGOUT_URL=

# 如果 X-Frame-Options 头干扰了像 Organizr 这样的工具，
# 你可以禁用它。这完全取决于你。
# 在框架中运行的应用程序有泄露信息给父框架的风险。
DISABLE_FRAME_HEADER=false

# 如果你使用的是古老的浏览器或任何版本的 Microsoft Edge / Internet Explorer（实际上是相同的）
# 你可以禁用内容安全策略头。
# 这会让你面临无法阻止潜在的 XSS 漏洞的风险。
# 这完全取决于你。
DISABLE_CSP_HEADER=false

# 如果你希望跟踪自己在 Firefly III 上的行为，请在此设置有效的分析跟踪信息。
# 目前只有我在演示站点上使用这个。但如果你愿意，也可以使用这个。
# 不要在 TRACKER_URL 前面添加 http:// 或 https://
# 目前唯一支持的跟踪器是 Matomo。
# 你可以从文件设置以下变量，通过附加 _FILE：
TRACKER_SITE_ID=
TRACKER_URL=

#
# Firefly III 支持 Webhook。这些是安全敏感的，必须手动启用。
#
ALLOW_WEBHOOKS=true                    # <-- 默认禁用webhooks，根据我的需要这里启动了

#
# 静态 cron 作业令牌在使用 Docker 并希望管理 cron 作业时很有用。
# 1. 将此令牌设置为任何 32 个字符的值（这一点很重要！）。
# 2. 在 cron URL 中使用此令牌而不是用户命令行令牌，该令牌可以在 /profile 找到
#
# 更多信息：https://docs.firefly-iii.org/how-to/firefly-iii/advanced/cron/
#
# 你可以从文件设置此变量，通过附加 _FILE
#
STATIC_CRON_TOKEN=JhdfKHdaHxxxxxxxxxxxxxxxxxGdafDAK
# 填写32 个字符；自动预算、经常易、账单警告和最新数据的货币汇率信息都需要使用cron，具体使用自行查看官方文档


# 你可以通过编辑这些环境变量来微调 Docker 容器的启动。
# 使用此功能需自行承担风险。禁用某些检查和功能可能导致大量不一致的数据。
# 但是，如果你知道自己在做什么，可以显著加快容器启动时间。
# 将每个值设置为 true 以启用，或 false 以禁用。

# 将此设置为 true 以构建 Firefly III 支持的所有区域设置。
# 这可能需要相当长的时间（几分钟）并且通常不推荐。
# 如果你希望更改或修改区域设置列表，可以使用以下命令启动 Docker 容器：
# `docker run -v locale.gen:/etc/locale.gen -e DKR_BUILD_LOCALE=true`
# 并确保你偏好的区域设置在你自己的 locale.gen 中。
DKR_BUILD_LOCALE=false

# 检查 SQLite 数据库是否存在。如果不使用 SQLite，可以跳过此步骤。
# 不会显著加快速度。
DKR_CHECK_SQLITE=true

# 除非你知道自己在做什么，否则请勿更改以下配置变量。
# APP_NAME=FireflyIII
BROADCAST_DRIVER=log
QUEUE_DRIVER=sync
CACHE_PREFIX=firefly
PUSHER_KEY=
IPINFO_TOKEN=
PUSHER_SECRET=
PUSHER_ID=
DEMO_USERNAME=
DEMO_PASSWORD=

#
# 禁用或启用运行余额列数据
# 请禁用此功能。这是一个非常实验性的功能。
#
USE_RUNNING_BALANCE=false

#
# v2 布局非常实验性。如果它崩溃了，你将得到两部分。
# 注意数据丢失的风险。
#
FIREFLY_III_LAYOUT=v1

#
# 请确保此 URL 匹配 Firefly III 安装的外部 URL。
# 它用于验证特定请求并生成电子邮件中的 URL。
#
APP_URL=http://localhost

注意: 请务必更改 APP_KEY 为一个安全的随机字符串。您可以使用在线工具生成它，或者在命令行中使用以下命令生成： head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo

步骤 3: 编写 docker-compose.yml

docker-compose.yml 文件定义了构成 Firefly III 环境的服务、网络和数据目录。以下是 docker-compose.yml 文件的示例：

services:
  app:
    image: fireflyiii/core:latest
    hostname: app
    container_name: firefly_iii_core
    restart: always
    volumes:
      - /data/firefly-iii:/var/www/html/storage/upload
    env_file: .env
    networks:
      - your-network
    ports:
      - 127.0.0.1:8888:8080					# 为了安全，映射端口只允许本地访问

  cron:
    #
    # 要使此功能生效，请在您的 .env 文件或环境变量中设置 STATIC_CRON_TOKEN，并将下面的 REPLACEME 替换为实际值
    # STATIC_CRON_TOKEN 必须 *恰好* 32 个字符长
    # 自动预算、经常易、账单警告和最新数据的货币汇率信息都依赖cron运行，根据你的需求配置
    image: alpine
    restart: always
    container_name: firefly_iii_cron
    command: sh -c "echo \"0 3 * * * wget -qO- http://app:8080/api/v1/cron/REPLACEME;echo\" | crontab - && crond -f -L /dev/stdout"
    networks:
      - your-network

networks:
    your-network:				            # 修改为实际的网络名称，应用网络也要修改
        external: true						# 表示外部网络，不用新建
        

步骤 4: 启动服务

现在一切准备就绪，可以启动服务了。在项目根目录下运行以下命令：

docker-compose up -d

这将下载必要的镜像并以分离模式启动所有服务。首次启动时可能需要一些时间，因为 Docker 需要下载镜像并初始化数据库。

步骤 5: 访问 Firefly III

一旦所有服务都已启动并运行，就可以通过浏览器访问 Firefly III。当然，由于我构建的容器只能内部访问，所以我配置了nginx反向代理(proxy_pass http://127.0.0.1:8888; )通过代理地址进行访问。如果您想直接通过服务器IP进行访问，在构建时允许映射端口外部访问就可以，然后使用服务器的IP+端口直接访问。

步骤 6: 完成安装

打开浏览器并访问您之前确定的 URL，按照屏幕上的指示完成 Firefly III 的安装过程。初次登录需要初始化并设置默认资产账户、货币单位、初始金额以及默认语言。

结语

通过以上步骤成功使用 Docker Compose 部署了 Firefly III。然后就可以轻松地管理和扩展个人财务数据。希望这个教程对你有帮助！

其实每个人都有自己的小技巧和习惯。不过，我觉得像 Firefly III 这样的工具确实能让生活变得更简单，尤其是当你不想被繁杂的账单和收支记录搞得头大时。也希望能帮到你更好地管理自己的财务。

祝你一切顺利，记得养成良好的理财习惯哟！✨