lamess / Firefly III 部署实践

Created Thu, 12 Mar 2026 14:21:16 +0800 Modified Thu, 12 Mar 2026 15:30:56 +0800
1658 Words
Firefly-iii Docker Nginx Cloudflare CDN

引言

Firefly III 是一款功能强大、界面优雅的开源个人财务管理工具。它能帮助你清晰地追踪收入与支出、管理预算和储蓄，真正掌控自己的财务数据。通过自托管的方式，所有敏感的财务信息都将保存在你自己的服务器上，杜绝了隐私泄露的风险。

本篇文章记录了使用 Docker Compose、SQLite、Nginx 及 Cloudflare，搭建起一个 Firefly III 个人记账服务。

准备工作

在开始之前，请确保具备以下条件：

  • 服务器：拥有 root 权限的云服务器（VPS）或物理服务器。
  • 域名：一个你自己的域名，并将其 DNS 管理权限托管到 Cloudflare。
  • 基础环境：服务器上已安装好 Docker、Docker Compose 和 Nginx。

部署步骤

采用官方推荐的 Docker Compose 方式进行部署，以简化服务的安装和管理。

第一步：准备目录与 docker-compose.yml

创建用于存放 Firefly III 所有数据的目录，并从官方仓库下载 docker-compose.yml 模板文件。

# 创建主目录及数据子目录
mkdir -p /opt/firefly-iii/upload /opt/firefly-iii/database /opt/firefly-iii/logs

# 进入主目录
cd /opt/firefly-iii

# 下载 docker-compose.yml 文件
wget https://raw.githubusercontent.com/firefly-iii/docker/main/docker-compose.yml

编辑 docker-compose.yml 文件，调整挂载路径并明确服务配置。为了简化部署，推荐使用 SQLite 数据库，因此官方模板中的 db 服务可以移除。

以下是修改后的 docker-compose.yml 内容：

services:
  app:
    image: fireflyiii/core:latest
    hostname: app
    container_name: firefly_iii_core
    restart: always
    ports:
      # 仅监听本地回环地址，通过 Nginx 暴露给外部
      - "127.0.0.1:8080:8080"
    volumes:
      # 将容器内的数据目录挂载到宿主机，实现数据持久化
      - /opt/firefly-iii/upload:/var/www/html/storage/upload
      - /opt/firefly-iii/database:/var/www/html/storage/database
      - /opt/firefly-iii/logs:/var/www/html/storage/logs
    env_file: .env
    networks:
      - firefly_iii

  cron:
    image: alpine
    restart: always
    container_name: firefly_iii_cron
    env_file: .env
    command: sh -c "
      apk add tzdata && \
      (ln -s /usr/share/zoneinfo/$$TZ /etc/localtime || true) && \
      echo \"0 3 * * * wget -qO- http://app:8080/api/v1/cron/$$STATIC_CRON_TOKEN;echo\"
      | crontab - && \
      crond -f -L /dev/stdout"
    networks:
      - firefly_iii
    depends_on:
      - app

networks:
  firefly_iii:
    driver: bridge

第二步：配置 .env 环境变量

环境变量文件 .env 用于存放敏感信息和个性化配置。先下载官方模板，再进行修改。

# 下载 .env 模板文件
wget -O .env https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example

# 生成一个随机的32位 APP_KEY
head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo

将上面命令生成的 APP_KEY 复制下来，然后编辑 .env 文件，修改以下关键配置：

# .env 文件需要修改的主要内容

# 网站所有者邮箱，用于在错误页面显示
SITE_OWNER=your-email@example.com

# 填入上一步生成的32位随机字符串
APP_KEY=PASTE_YOUR_APP_KEY_HERE

# 默认语言和时区
DEFAULT_LANGUAGE=zh_CN
TZ=Asia/Shanghai

# 信任所有反向代理，使用 Nginx 和 Cloudflare
TRUSTED_PROXIES=**

# --- 数据库配置 ---
# 使用 SQLite，简单方便
DB_CONNECTION=sqlite
# 注释掉所有 PostgreSQL/MySQL 相关配置
# DB_HOST=db
# DB_PORT=3306
# DB_DATABASE=firefly
# DB_USERNAME=firefly
# DB_PASSWORD=secret_firefly_password

# --- 定时任务配置 ---
# 设置一个随机的32位字符串作为 Cron 任务的访问令牌
STATIC_CRON_TOKEN=PASTE_A_NEW_RANDOM_32_CHAR_STRING_HERE

# 设置为最终访问的域名
APP_URL=https://firefly.your-domain.com

请务必将 APP_KEY、STATIC_CRON_TOKEN 和 APP_URL 替换为实际值。

第三步：启动 Firefly III 服务

完成配置后，在 /opt/firefly-iii 目录下启动服务。

# -d 表示后台运行，--pull=always 确保每次启动都拉取最新镜像
docker-compose up -d --pull=always

服务启动后，可以通过以下命令检查容器状态：

docker-compose ps

确认 firefly_iii_core 和 firefly_iii_cron 两个容器都显示为 running 或 up，表示服务已成功启动。

第四步：配置 Nginx 反向代理

为了使用域名和 HTTPS 访问服务，我们需要配置 Nginx 作为反向代理。

在 Nginx 的配置目录（如 /etc/nginx/conf.d/）下创建一个新的配置文件 firefly.conf：

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name firefly.your-domain.com; # 替换为实际域名

    # SSL 证书路径，请使用你自己的证书
    ssl_certificate /path/to/your/fullchain.pem;
    ssl_certificate_key /path/to/your/privkey.pem;

    # 安全相关的 Header，增强网站安全性
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "same-origin" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        # 将请求转发给本地的 Firefly III 服务
        proxy_pass http://127.0.0.1:8080;
        
        # 传递必要的 Header
        proxy_set_header Host $host;
        # 如果使用 Cloudflare，用 $http_cf_connecting_ip 获取真实 IP
        # 如果不使用，请改为 $remote_addr
        proxy_set_header X-Real-IP $http_cf_connecting_ip;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # 调整超时设置
        proxy_connect_timeout 60s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;
    }
}

配置完成后，检查 Nginx 语法并重新加载：

nginx -t
systemctl reload nginx

第五步：配置 CDN 与防火墙

  1. Cloudflare DNS：在 Cloudflare 中添加一条 A 记录，将实际域名（如 firefly.your-domain.com）指向服务器的公网 IP，并确保开启了 CDN 功能（橙色云朵）。
  2. SSL/TLS 设置：在 Cloudflare 的 SSL/TLS 选项卡中，将加密模式设置为 Full (Strict)，以确保端到端的全程加密。
  3. 防火墙规则：在服务器防火墙（如 ufw 或 firewalld）中增加设置，仅允许来自 Cloudflare IP 列表 的流量访问 443 端口，阻止其他所有外部 IP 的直接访问。
  4. 安全规则：配置其他必要的安全规则，设置网页访问时进行自动质询，拦截非国内的服务访问。

初始化设置

完成以上所有步骤后，通过浏览器访问域名 https://firefly.your-domain.com。进入 Firefly III 的初始化页面。按照提示创建管理员账户、设置默认货币，即可开始记账之旅！

数据备份

数据无价，在部署完成后，还需要定期备份整个 /opt/firefly-iii 目录，防止数据丢失。