Ubuntu 22.04 安装 FOSSBilling 0.8.8 指南

目标：在一台 Ubuntu 22.04 服务器上完成 FOSSBilling 0.8.8 的生产式安装——从 PHP 8.3 运行时、MariaDB 11.4 数据库的依赖链搭建，到官方安装向导的逐字段实测与安装后加固，全部命令与回显均来自真实服务器实测（实测日期 2026-10-23）。

一、环境信息

本文所有命令在以下服务器环境中实测执行：

项目	值
操作系统	Ubuntu 22.04.5 LTS（`PRETTY_NAME="Ubuntu 22.04.5 LTS"`，`VERSION_ID="22.04"`）
内核	6.8.0-138-generic
主机名	billing-server
内网 IP	192.168.1.62
对外服务端口	8148（Apache 监听）
Web 服务器	Apache/2.4.52 (Ubuntu)
PHP	8.3.36（cli，NTS，via ppa:ondrej/php）
数据库	11.4.13-MariaDB（官方仓库安装）
磁盘占用	安装完成 `/var/www/html` 约 100M

cat /etc/os-release 与版本核验回显：

$ grep -E "PRETTY_NAME|VERSION_ID" /etc/os-release
PRETTY_NAME="Ubuntu 22.04.5 LTS"
VERSION_ID="22.04"
$ uname -r
6.8.0-138-generic
$ hostname
billing-server

二、前置条件

2.1 系统与软件源准备

apt-get update
apt-get -y upgrade
apt-get -y install curl wget unzip software-properties-common gnupg cron

cron 包用于承载 FOSSBilling 的周期任务（安装完成页会提示配置 5 分钟一次的 cron.php 调度，见 4.5 节）。

2.2 安装 Apache

apt-get -y install apache2
apache2 -v

版本核验回显：

Server version: Apache/2.4.52 (Ubuntu)

2.3 安装 PHP 8.3 及扩展（依赖链第一环）

FOSSBilling 0.8.x 要求 PHP 8.3 / 8.4 / 8.5（来源：docs.fossbilling.org「Requirements」页，查询日期 2026-10-23）。Ubuntu 22.04 官方源只有 PHP 8.1，需先接入 ondrej/php PPA：

add-apt-repository -y ppa:ondrej/php
apt-get update
apt-get -y install php8.3 libapache2-mod-php8.3 \
  php8.3-mysql php8.3-intl php8.3-curl php8.3-mbstring \
  php8.3-xml php8.3-gd php8.3-opcache php8.3-zip
php -v

版本核验回显：

PHP 8.3.36 (cli) (built: Oct 21 2026 14:31:50) (NTS)

必需扩展逐项核验（官方必需：curl、dom、iconv、intl、json、openssl、pdo_mysql、xml、zlib；推荐：mbstring、opcache、imagick 或 gd）：

php -m | grep -iE "curl|dom|intl|iconv|json|openssl|pdo_mysql|xml|zlib|mbstring|opcache|^gd$"

实测回显（全部命中，无需补装）：

curl
dom
gd
iconv
intl
json
libxml
mbstring
openssl
pdo_mysql
random
SimpleXML
xml
xmlreader
xmlwriter
Zend OPcache
zlib

2.4 安装 MariaDB 11.4（依赖链第二环）

FOSSBilling 0.8.x 要求 MariaDB 11.4 或更高（或 MySQL 8.4+）。Ubuntu 22.04 官方源是 MariaDB 10.6，需接入 MariaDB 官方仓库：

curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | bash -s -- --mariadb-server-version=11.4
apt-get update
apt-get -y install mariadb-server mariadb-client
mariadb --version

版本核验回显：

mariadb from 11.4.13-MariaDB, client 15.2 for debian-linux-gnu (x86_64) using  EditLine wrapper

2.5 创建数据库与专用账号

数据库字符集必须为 utf8mb4（官方要求，默认排序规则 utf8mb4_unicode_ci）：

mariadb -uroot -p <<'SQL'
CREATE DATABASE fossbilling CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'fossbilling'@'localhost' IDENTIFIED BY 'q1w2e3r4';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, LOCK TABLES, CREATE VIEW ON fossbilling.* TO 'fossbilling'@'localhost';
FLUSH PRIVILEGES;
SQL

⚠️ 权限要点：除常规增删改查与 DDL 权限外，LOCK TABLES 必须显式授予——官方 Requirements 页未把 LOCK TABLES 列入数据库要求，但安装脚本的 install/sql/content.sql 中包含 32 处 LOCK TABLES 语句，缺失该权限时安装向导会直接 500（见 9.2 节排障实录）。CREATE VIEW 同理在初始化视图中使用。

账号核验：

mariadb -ufossbilling -pq1w2e3r4 -e "SHOW GRANTS FOR CURRENT_USER;"

实测回显：

Grants for fossbilling@localhost
GRANT USAGE ON *.* TO `fossbilling`@`localhost` IDENTIFIED BY PASSWORD '*0971389F8E7F1AEB999104BDA7A0FA145087F348'
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, LOCK TABLES, CREATE VIEW ON `fossbilling`.* TO `fossbilling`@`localhost`

三、版本选型说明

本文安装 0.8.8，为 GitHub Releases 上的最新稳定版（release 更新时间 2026-10-03T07:03:48Z，查询日期 2026-10-23）。
官方发行包为 zip 压缩包（含 vendor 依赖，无需再执行 composer install）：

wget -O /root/FOSSBilling-0.8.8.zip https://github.com/FOSSBilling/FOSSBilling/releases/download/0.8.8/FOSSBilling-0.8.8.zip
sha256sum /root/FOSSBilling-0.8.8.zip

校验和实测回显（与官方 release 资产一致）：

6ab8cb04ad8ace31622caa1d999dbc3b1ffd89143bcd650986d1302830fb08a5  /root/FOSSBilling-0.8.8.zip

文件大小 30,414,168 字节（约 29 MiB）。
运行时兼容结论：0.8.8 支持 PHP 8.3/8.4/8.5，本文选 8.3 稳妥线；MariaDB 选 11.4 LTS（官方最低要求线）。

四、方案 A：官方安装包在线安装（推荐）

4.1 解压部署到网站根目录

mkdir -p /var/www/html
cd /var/www/html
unzip -qo /root/FOSSBilling-0.8.8.zip
chown -R www-data:www-data /var/www/html
find /var/www/html -type d -exec chmod 755 {} \;
find /var/www/html -type f -exec chmod 644 {} \;

⚠️ 属主要点：安装器需要在安装过程中写 config.php、data/ 缓存目录与主题配置文件，属主必须是 Apache 运行用户 www-data。属主为 root 时安装向导会报 Failed to copy ... Permission denied（见 9.5 节排障实录）。

部署后的目录结构核验：

ls -F /var/www/html/

实测回显：

LICENSE
README.md
config-sample.php
config.php
console.php
cron.php
data/
di.php
index.php
ipn.php
library/
load.php
locale/
modules/
public/
rewrite-missing.html
robots.txt
themes/
vendor/

（config.php 为安装向导完成后生成；初始状态只有 config-sample.php。）

4.2 配置 Apache 虚拟主机与重写规则

FOSSBilling 依赖 .htaccess 实现 /admin 等简洁路由，AllowOverride 必须放开并启用 mod_rewrite：

a2enmod rewrite

实测回显：

Enabling module rewrite.
To activate the new configuration, you need to run:
  service apache2 restart

编辑 /etc/apache2/ports.conf，将默认监听端口改为 8148：

Listen 8148

编辑 /etc/apache2/sites-available/000-default.conf（全文如下）：

<VirtualHost *:8148>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html
    <Directory /var/www/html>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

生效并重启：

a2ensite 000-default
apachectl -k restart

4.3 运行安装向导

浏览器访问 http://192.168.1.62:8148/install/，会 302 跳转到 /install/install.php 进入向导。向导依次为环境自检页（PHP 版本与扩展、数据库驱动逐项绿灯）→ 参数填写页 → 安装执行页。

参数填写页字段与本文实测取值：

字段	说明	实测取值
system_url	站点对外访问地址（含端口，尾斜杠）	`http://192.168.1.62:8148/`
database_hostname	数据库地址	`localhost`
database_port	数据库端口	`3306`
database_name	数据库名	`fossbilling`
database_username	数据库账号	`fossbilling`
database_password	数据库密码	`q1w2e3r4`
admin_name	管理员姓名	`Admin`
admin_email	管理员邮箱	`admin@quzuo.net`
admin_password	管理员密码（≥8 位、含数字与小写、含大写）	`Q1w2e3r4`
currency_code	默认货币	`USD`
error_reporting	匿名错误上报开关	关闭

提交后进入安装执行页，脚本依次完成数据库连接校验 → 管理员密码校验 → 建表与基础数据导入（60 张表）→ 生成 config.php → 输出完成页。

安装成功页（节选）实测文本：

Installation Completed
FOSSBilling is ready. Review these final checks before you start accepting orders.

Remove Installer
The ./install/ folder is normally deleted automatically. If it still exists, remove it before using FOSSBilling.

Configuration Permission
Restrict write access to config.php after setup.
chmod 644 /var/www/html/config.php

Set up Cron Job
Run the FOSSBilling cron task every five minutes. The official Docker image configures this automatically. For other installs, add this to your crontab.
*/5 * * * * php /var/www/html/cron.php

Next, open the customer area or sign in to the admin dashboard.
Customer Area    Admin Dashboard

完成页同时给出三步收尾指引：确认 ./install/ 已删除、收紧 config.php 写权限、配置 cron。安装器在非 debug 模式下会自动删除 install/install.php（实测安装后 install/ 目录中仅剩 assets、index.php、session.php、sql 等资源文件，install.php 已消失）。

4.4 安装后收尾

# 收紧配置文件写权限
chmod 644 /var/www/html/config.php
# 确认安装器入口已移除
ls /var/www/html/install/

配置 crontab（安装完成页指示的周期任务）：

echo "*/5 * * * * php /var/www/html/cron.php" | crontab -u www-data -
crontab -u www-data -l

实测回显：

*/5 * * * * php /var/www/html/cron.php

cron 执行记录落在 data/log/cron/ 目录（文件名按日期滚动）：

$ ls /var/www/html/data/log/cron/
cron-2026-10-23.log
$ tail -2 /var/www/html/data/log/cron/cron-2026-10-23.log
[23-Oct-2026 06:04:11 UTC] cron.INFO: Executed action to try cover unpaid invoices with client credits.
[23-Oct-2026 06:04:11 UTC] cron.INFO: Executed action to activate paid invoices.

数据库表数量核验：

mariadb -uroot -p -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='fossbilling';"

实测回显：

4.5 验证

前台与后台可访问性实测：

curl -sI http://127.0.0.1:8148/ | head -4
curl -s -o /dev/null -w "front=%{http_code}\n" http://127.0.0.1:8148/
curl -s -o /dev/null -w "admin-login=%{http_code}\n" http://127.0.0.1:8148/admin/staff/login

实测回显：

HTTP/1.1 200 OK
Date: Fri, 23 Oct 2026 06:19:41 GMT
Server: Apache/2.4.52 (Ubuntu)
Set-Cookie: fossbilling_session=c2il7qvadqhbtd42n1g3pnmmce; path=/; HttpOnly; SameSite=Strict
front=200
admin-login=200

浏览器访问 http://192.168.1.62:8148/admin 进入管理区登录页，使用 admin / Q1w2e3r4 登录；客户区为站点首页 http://192.168.1.62:8148/。

五、方案 B：离线安装（内网环境）

与方案 A 的差异仅在安装包获取方式，服务器无需访问公网：

联网机器下载：在一台可访问公网的机器上下载 0.8.8 发行包，并核对 sha256（同 3 节，6ab8cb04ad8ace31622caa1d999dbc3b1ffd89143bcd650986d1302830fb08a5）。
传输到服务器：scp FOSSBilling-0.8.8.zip root@192.168.1.62:/root/。
部署与向导：解压、属主、Apache 配置、安装向导步骤与方案 A 的 4.1–4.5 完全一致。
离线环境注意：system_url 必须填写内网可达地址（如 http://192.168.1.62:8148/），否则生成的 config.php 中 url 项会导致后台跳转异常；匿名错误上报（error_reporting）建议保持关闭。

六、方案 C：源码构建（开发尝鲜）

面向参与贡献或本地定制打包的场景，官方「Building from Source」文档给出的构建路径（来源：docs.fossbilling.org/getting-started/building/，查询日期 2026-10-23）：

前置要求：PHP 8.3 或更新、Composer（最新版）、Node.js 且 npm 11 或更新。

git clone https://github.com/FOSSBilling/FOSSBilling.git
cd FOSSBilling
composer install
npm install
npm run build

主题单独构建：npm run build-admin_default 与 npm run build-huraga；主题开发模式进入 src/themes/huraga 执行 npm run dev。本地快速预览可在 src 目录执行 php -S localhost:8000。

方案 C 产出的代码位于仓库 src/ 目录，与发行包的目录层级不同（发行包已把 src/ 内容置于根），生产部署请使用方案 A/B 的发行包，源码方式仅用于开发调试。

七、方案对比与选择建议

维度	方案 A：官方安装包在线	方案 B：离线安装包	方案 C：源码构建
适用场景	生产推荐，标准 LAMP 服务器	内网/隔离环境生产部署	贡献代码、定制开发
版本来源	GitHub Releases 稳定版	同 A（预先下载）	git 主分支/指定 tag
依赖处理	发行包自带 vendor	自带 vendor	需 Composer + npm 构建
升级便利	直接换包重解压	手动传包	拉取源码重新构建
生产建议	✅ 首选	✅ 等效 A	❌ 不建议直接投产

选择建议：常规生产用方案 A；服务器不出网先在跳板机完成方案 B 的下载校验；只有改代码才走方案 C。

八、配置说明

安装完成后与运行直接相关的三类配置：

Apache：虚拟主机与 AllowOverride All 是 /admin 路由可用性的前提（见 4.2）；生产建议补充 TLS（certbot 或自有证书）并把 system_url 换为 HTTPS 地址。
PHP：Ubuntu 默认 upload_max_filesize = 2M、post_max_size = 8M，如需在客户区上传较大附件，调整 /etc/php/8.3/apache2/php.ini 中这两项并重启 Apache；时区建议同步设置 date.timezone（FOSSBilling 自身时区由 config.php 的 i18n.timezone 控制，见《FOSSBilling 0.8.8 配置参数详解》）。
周期任务：*/5 * * * * php /var/www/html/cron.php 承担账单生成、服务挂起、催款邮件等核心业务调度；crontab 缺失时前台正常但账单不会自动出账。config.php 中 disable_auto_cron 保持默认（false）之外，若开启则系统 cron 为唯一触发渠道。

九、常见问题（FAQ）

以下五条均为本次实测中真实触发并解决的故障记录。

9.1 安装向导报错：Admin password must include at least one uppercase letter

现象：提交向导后页面返回 500，失败页正文为：

Installation Failure
FOSSBilling could not complete the installation.
Admin password must include at least one uppercase letter.

原因：0.8.x 管理员密码校验要求至少 8 位、含数字、含小写、含大写。q1w2e3r4 缺大写字母被拒。
解决：使用满足全部规则的密码（如 Q1w2e3r4）重新提交。

9.2 安装向导报错：SQLSTATE[42000] … 1044 Access denied

现象：密码合规后安装仍失败，失败页正文为：

Installation Failure
FOSSBilling could not complete the installation.
SQLSTATE[42000]: Syntax error or access violation: 1044 Access denied for user 'fossbilling'@'localhost' to database 'fossbilling'

原因：安装脚本的 install/sql/content.sql 含 32 处 LOCK TABLES 语句，而按官方 Requirements 页惯性只授了增删改查与 DDL 权限，缺 LOCK TABLES。
解决：补授权限后重新执行向导：

mariadb -uroot -p -e "GRANT LOCK TABLES, CREATE VIEW ON fossbilling.* TO 'fossbilling'@'localhost'; FLUSH PRIVILEGES;"

若失败发生在建表中途，重试前建议删除数据库重建（避免 1050 表已存在错误）：

mariadb -uroot -p -e "DROP DATABASE fossbilling; CREATE DATABASE fossbilling CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

9.3 前台正常但 /admin 返回 404

现象：安装完成，http://192.168.1.62:8148/ 正常，但访问 /admin 报 Apache 404。
原因：Ubuntu Apache 默认 AllowOverride None，FOSSBilling 根目录 .htaccess 的重写规则未生效，/admin 路由无法映射到 index.php。
解决：虚拟主机 <Directory /var/www/html> 内设置 AllowOverride All，并 a2enmod rewrite 后 apachectl -k restart（见 4.2）。验证 curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8148/admin/staff/login 返回 200 即恢复。

9.4 报错：The template cache directory could not be written to

现象：以 root 执行过 rm -rf /var/www/html/data/cache/* 之类的清理后，前台整站 500。
原因：root 删除并隐式重建 cache 目录后，目录属主变为 root，Apache 的 www-data 无法写入 Twig 编译缓存。
解决：恢复属主：

chown -R www-data:www-data /var/www/html/data

复验前台返回 200。同类问题也适用于 data/log 等运行时目录。

9.5 安装向导报错：Failed to copy … Permission denied

现象：网站根目录属主为 root 时提交向导，失败页正文含：

Failed to copy "/var/www/html/themes/huraga/config/settings_data.json.example" to "/var/www/html/themes/huraga/config/settings_data.json" because target file could not be opened for writing: fopen(/var/www/html/themes/huraga/config/settings_data.json): Failed to open stream: Permission denied

原因：安装器在收尾阶段要写主题配置、生成 config.php 并创建 data 运行时目录，全流程需要 www-data 写权限。
解决：chown -R www-data:www-data /var/www/html 后重新提交向导。

十、卸载与清理

按依赖的相反顺序完整移除：

# 1. 停用并移除站点与重写模块（如服务器另作他用）
a2dissite 000-default
apachectl -k stop

# 2. 移除周期任务
crontab -u www-data -r

# 3. 删除程序与数据文件
rm -rf /var/www/html

# 4. 删除数据库与账号
mariadb -uroot -p <<'SQL'
DROP DATABASE IF EXISTS fossbilling;
DROP USER IF EXISTS 'fossbilling'@'localhost';
FLUSH PRIVILEGES;
SQL

# 5. 如需彻底卸载运行时（可选，会影响服务器上其他 PHP 应用，慎用）
apt-get -y purge 'php8.3-*' libapache2-mod-php8.3 && apt-get -y autoremove
apt-get -y purge mariadb-server mariadb-client && apt-get -y autoremove

卸载数据库会同时删掉其中全部数据；若只重装 FOSSBilling 而保留数据，跳过第 4 步即可。

十一、参考链接

FOSSBilling 0.8.8 Release 页：https://github.com/FOSSBilling/FOSSBilling/releases/tag/0.8.8
官方 Requirements（运行环境要求）：https://docs.fossbilling.org/getting-started/requirements/
官方 Installation 指南：https://docs.fossbilling.org/getting-started/installation/
官方 Building from Source：https://docs.fossbilling.org/getting-started/building/
MariaDB 官方仓库脚本：https://mariadb.org/download/?t=repo-config
ondrej/php PPA：https://launchpad.net/~ondrej/+archive/ubuntu/php
本专栏选型认知：《FOSSBilling 0.8.8 介绍与选型指南》
本专栏配置手册：《FOSSBilling 0.8.8 配置参数详解》

本专栏系列：《FOSSBilling 0.8.8 API 使用详解》。