Firefly III 部署指南 (PHP 8.0, 非Docker)

Firefly III 部署指南 (PHP 8.0, 非Docker)

简介

Firefly III 是一款开源的个人财务管理工具，提供预算管理、交易记录、报表等功能。

下载地址

官方GitHub仓库: https://github.com/firefly-iii/firefly-iii

系统要求

• PHP 8.0+

• MySQL 5.7+/MariaDB 10.2+

• Composer 2.0+

• Web服务器(Apache/Nginx)

安装步骤

1. 安装Composer

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

2. 下载Firefly III

git clone https://github.com/firefly-iii/firefly-iii.git
cd firefly-iii
git checkout stable

如果安装最新版本则需要PHP8.4版本
若你的系统配置PHP8.0以上的版本，Firefly III可以选择安装：5.70~6.0

选择：Firefly III 5.7.16 ，点未详细信息下载此版本。如果下载不了，可以在评论区说明，或者私信@我

3. 安装依赖

composer install --no-dev --prefer-dist
composer install --no-dev  # 安装生产环境依赖
php artisan key:generate  # 生成应用密钥
php artisan migrate --seed  # 数据库迁移与初始化

PHP版本兼容性‌
Firefly III官方要求PHP≥8.1，但PHP 8.0可通过以下调整临时兼容13：
修改composer.json中PHP版本约束为"php": "^8.0"
安装时添加--ignore-platform-reqs参数跳过版本检查：
bashCopy Codecomposer install --no-dev --ignore-platform-reqs
‌必需扩展清单‌
PHP 8.0需确保安装以下扩展15：
bashCopy Codesudo apt install php8.0-{curl,gd,mbstring,zip,intl,bcmath,pdo-mysql}

composer install --no-dev --optimize-autoloader --no-interaction
php artisan key:generate
php artisan migrate --seed --forcechmod -R 775 storage bootstrap/cachechown -R www-data:www-data .  # 根据实际Web用户调整

4. 配置环境

复制示例环境文件:

cp .env.example .env

‌禁用调试模式‌
确保.env中APP_DEBUG=false，避免敏感信息泄露。

编辑.env文件，配置数据库连接:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=firefly
DB_USERNAME=firefly
DB_PASSWORD=your_password

5. 生成应用密钥

php artisan key:generate
php artisan migrate --seed --force  # 强制生产环境执行

6. 创建数据库

mysql -u root -p
CREATE DATABASE firefly;
CREATE USER 'firefly'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON firefly.* TO 'firefly'@'localhost';
FLUSH PRIVILEGES;
EXIT;

7. 导入数据库结构

php artisan migrate --seed

8. 设置存储权限

chown -R www-data:www-data storage
chmod -R 775 storage

9. 配置Web服务器

Apache配置示例:

<VirtualHost *:80>
    ServerName firefly.example.com
    DocumentRoot /path/to/firefly-iii/public
    
    <Directory /path/to/firefly-iii/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nginx配置示例:

server {
    listen 80;
    server_name firefly.example.com;
    root /path/to/firefly-iii/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
    }
}

10. 完成安装

访问配置的域名完成安装向导。

常见问题解决‌

• ‌PHP 8.0兼容性警告‌：部分依赖库可能抛出警告，但不影响核心功能运行
  

• ‌中文翻译缺失‌：可手动编辑resources/lang/zh_CN/下的语言文件补充内容
  

• ‌定时任务设置‌：添加Cron任务定期执行php artisan schedule:run
  

中文支持优化‌

1. ‌语言包检查‌

• Firefly III官方已内置中文翻译，通过 APP_LOCALE=zh_CN 激活16

• 如遇翻译缺失，可手动编辑 resources/lang/zh_CN/*.php 文件补充

2. ‌时区设置‌

   envCopy CodeAPP_TIMEZONE=Asia/Shanghai  # 在.env中配置时区

‌四、常见问题‌

• ‌PHP扩展缺失‌：通过 php -m 检查已加载模块，缺失时执行 sudo apt install php-{扩展名}5

• ‌权限错误‌：确保 storage 目录可写，日志文件权限正确7

• ‌数据库连接失败‌：检查 .env 中数据库配置与用户权限是否匹配18