PostgreSQL 数据库指南

FLYX 默认使用 SQLite 作为数据库，同时也内置了对 PostgreSQL 的完整支持。本文档介绍如何使用 PostgreSQL 部署面板、从 SQLite 迁移以及日常维护。

一、SQLite 与 PostgreSQL 对比

特性	SQLite	PostgreSQL
部署复杂度	零配置，开箱即用	需要额外的数据库服务
并发性能	适合小规模单机使用	支持高并发读写
数据规模	适合中小规模数据	适合大规模数据
备份与恢复	直接复制文件	支持逻辑备份与物理备份
高可用	不支持	支持主从复制、流复制

建议：如果你只是个人使用或小团队使用，SQLite 完全够用。如果节点多，推荐使用 PostgreSQL。

---

二、环境变量说明

以下环境变量用于配置数据库连接，在 .env 文件或 Docker Compose environment 中设置。

后端服务 (backend) 使用

变量名	说明	默认值	示例
DB_TYPE	数据库类型，sqlite 或 postgres	sqlite	postgres
DATABASE_URL	PostgreSQL 连接字符串（仅 DB_TYPE=postgres 时必填）	空	postgres://flux_panel:密码@postgres:5432/flux_panel?sslmode=disable
DB_PATH	SQLite 数据库文件路径（仅 DB_TYPE=sqlite 时使用）	/app/data/gost.db	/app/data/gost.db

PostgreSQL 容器使用

变量名	说明	默认值
POSTGRES_DB	数据库名称	flux_panel
POSTGRES_USER	数据库用户名	flux_panel
POSTGRES_PASSWORD	数据库密码	flux_panel_change_me

⚠️ 安全提示：生产环境中请务必修改 POSTGRES_PASSWORD 为强密码，不要使用默认值！

---

三、全新部署（Docker Compose + PostgreSQL）

安装脚本会根据环境自动下载对应的 Compose 配置并保存为 docker-compose.yml。默认使用 SQLite，只需配置环境变量即可切换到 PostgreSQL。

1. 创建 .env 文件

在 docker-compose 同目录创建 .env 文件：

# 基础配置
JWT_SECRET=替换为你的密钥
BACKEND_PORT=6365
FRONTEND_PORT=6366

# PostgreSQL 配置
DB_TYPE=postgres
DATABASE_URL=postgres://flux_panel:替换为强密码@postgres:5432/flux_panel?sslmode=disable

POSTGRES_DB=flux_panel
POSTGRES_USER=flux_panel
POSTGRES_PASSWORD=替换为强密码

⚠️ DATABASE_URL 中的密码必须与 POSTGRES_PASSWORD 保持一致。

2. 启动服务

docker compose up -d

3. 验证

# 检查所有容器是否正常运行
docker ps

# 查看后端日志，确认连接 PostgreSQL 成功
docker logs flux-panel-backend

# 查看 PostgreSQL 容器状态
docker logs flux-panel-postgres

---

四、从 SQLite 迁移到 PostgreSQL

如果你已经在使用 SQLite 并且希望迁移到 PostgreSQL，请按照以下步骤操作。

快速方式：脚本菜单一键迁移（推荐）

如果你是通过安装脚本部署面板，可直接执行：

./panel_install.sh
# 选择 4. 迁移到 PostgreSQL

脚本会自动完成以下操作：

• 备份 SQLite 数据到当前目录（gost.db.bak）
• 启动并等待 PostgreSQL 健康检查通过
• 使用 pgloader 导入 SQLite 数据
• 自动写入 .env 的 DB_TYPE=postgres 与 DATABASE_URL
• 重启服务并等待后端健康检查

手动方式：按步骤迁移

1. 备份 SQLite 数据

# 停止所有服务
docker compose down

# 备份 SQLite 数据文件到当前目录
docker run --rm -v sqlite_data:/data -v "$(pwd)":/backup alpine sh -c "cp /data/gost.db /backup/gost.db.bak"

2. 配置 PostgreSQL 环境变量

在 .env 文件中添加 PostgreSQL 配置（参考上方"环境变量说明"）。

3. 仅启动 PostgreSQL

docker compose up -d postgres

等待 PostgreSQL 完全就绪：

# 检查 PostgreSQL 健康状态
docker inspect --format='{{.State.Health.Status}}' flux-panel-postgres
# 输出 "healthy" 表示就绪

4. 使用 pgloader 迁移数据

source .env
docker run --rm \
  --network gost-network \
  -v sqlite_data:/sqlite \
  dimitri/pgloader:latest \
  pgloader /sqlite/gost.db "postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}"

📌 建议直接从 .env 读取 POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB，避免手填密码导致认证失败。

5. 启动全部服务

source .env
export DB_TYPE=postgres
export DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable"
docker compose up -d

6. 验证迁移

登录面板后，检查以下数据是否完整：

• 用户列表和权限
• 节点信息和状态
• 隧道配置
• 转发规则
• 流量统计数据

---

五、独立 PostgreSQL（非 Docker）

如果你不想使用 Docker Compose 中自带的 PostgreSQL 容器，也可以连接外部的 PostgreSQL 实例。

1. 准备 PostgreSQL

在目标 PostgreSQL 服务器上创建数据库和用户：

CREATE USER flux_panel WITH PASSWORD '你的强密码';
CREATE DATABASE flux_panel OWNER flux_panel;

2. 配置连接

修改 .env 文件，将 DATABASE_URL 指向外部 PostgreSQL：

DB_TYPE=postgres
DATABASE_URL=postgres://flux_panel:你的强密码@数据库地址:5432/flux_panel?sslmode=disable

📌 如果 PostgreSQL 在远程服务器且启用了 SSL，请将 sslmode=disable 改为 sslmode=require 或 sslmode=verify-full。

3. 停用内置 PostgreSQL 容器（可选）

如果使用外部 PostgreSQL，可以在启动时不启动内置的 postgres 服务：

docker compose up -d backend frontend

---

六、数据备份与恢复

逻辑备份（pg_dump）

# 备份（在 Docker 环境下）
docker exec flux-panel-postgres pg_dump -U flux_panel flux_panel > backup_$(date +%Y%m%d_%H%M%S).sql

# 恢复
docker exec -i flux-panel-postgres psql -U flux_panel flux_panel < backup_20260101_120000.sql

定时备份（cron）

创建备份脚本 /opt/flvx/backup.sh：

#!/bin/bash
BACKUP_DIR="/opt/flvx/backups"
mkdir -p "$BACKUP_DIR"
docker exec flux-panel-postgres pg_dump -U flux_panel flux_panel | gzip > "$BACKUP_DIR/flvx_$(date +%Y%m%d_%H%M%S).sql.gz"
# 清理 30 天前的备份
find "$BACKUP_DIR" -name "flvx_*.sql.gz" -mtime +30 -delete

添加 cron 任务（每天凌晨 3 点执行）：

chmod +x /opt/flvx/backup.sh
echo "0 3 * * * /opt/flvx/backup.sh" | crontab -

---

七、常见问题

Q: 切换到 PostgreSQL 后启动失败，提示连接被拒绝？

A:

1. 确认 PostgreSQL 容器已启动并处于 healthy 状态：docker ps。
2. 确认 DATABASE_URL 中的主机名、端口、用户名、密码正确。
3. 在 Docker Compose 环境下，主机名应为 postgres（服务名），而非 localhost。

Q: pgloader 迁移时报错？

A:

1. 确认 PostgreSQL 容器已完全就绪（状态为 healthy）。
2. 确认 --network gost-network 参数正确，使 pgloader 容器与 PostgreSQL 在同一网络中。
3. 如果数据库已有表结构，pgloader 可能会报冲突。可以先清空目标数据库后重试。

Q: 如何查看当前使用的数据库类型？

A: 查看后端容器的 DB_TYPE 环境变量：

docker exec flux-panel-backend printenv DB_TYPE

Q: 可以同时使用 SQLite 和 PostgreSQL 吗？

A: 不可以。DB_TYPE 只能设置为 sqlite 或 postgres 之一。后端启动时根据此配置连接对应的数据库。

Q: PostgreSQL 数据存储在哪里？

A: 在 Docker Compose 部署中，PostgreSQL 数据存储在名为 postgres_data 的 Docker Volume 中。可以通过以下命令查看：

docker volume inspect postgres_data