BioF3 生产切 PostgreSQL 操作手册

配套代码：scripts/biof3-pg-cutover.sh、scripts/backup-pg.sh
总览：docs/ops-postgres-migration.md

---

0. 前提

• 阿里云 RDS PostgreSQL 已建，Dell 能 psql "$DATABASE_URL" -c 'SELECT 1'
• 安全组：仅 Dell（及跳板） 可访问 5432
• 仓库已 ./deploy.sh --push 含 db.js、db-*-pg.js、migrations/pg/*、helpers/analytics-users.js 等
• 维护窗口 30–60 分钟（停写或低峰）

---

1. 准备 RDS 连接串

在 Dell /etc/biof3.env 先注释 旧行，追加（示例）：

# DATABASE_URL=postgres://biof3_app:PASSWORD@pgm-xxxxx.pg.rds.aliyuncs.com:5432/biof3

先不要 pm2 restart，等导入完成再开。

---

2. Dell 上执行（推荐顺序）

cd /opt/biof3-r-server   # 或从本机 ssh 上去

# 2.1 停服务，最后一次 SQLite 备份
pm2 stop biof3-r-server
./backup.sh

# 2.2 侧车库：Copilot / page_views 等（切 PG 后 P2 仍读 sqlite）
cp -a biof3.db biof3-aux.sqlite

# 2.3 建 PG 表 + 导入（在仓库根目录有 scripts 时）
cd /path/to/BioF3   # 或把 scripts 拷到 Dell
export DATABASE_URL='postgres://...'
export BIOF3_DB_PATH=/opt/biof3-r-server/biof3.db

npm run db:pg-migrate
npm run db:sqlite-to-pg:dry
npm run db:sqlite-to-pg

# 2.4 校验（psql）
psql "$DATABASE_URL" -c "SELECT COUNT(*) FROM users;"
psql "$DATABASE_URL" -c "SELECT key FROM site_settings WHERE key='guest_permissions';"
psql "$DATABASE_URL" -c "SELECT COUNT(*) FROM projects;"

或使用一键脚本（在仓库根目录）：

export DATABASE_URL='...'
export BIOF3_DB_PATH=/opt/biof3-r-server/biof3.db
./scripts/biof3-pg-cutover.sh --migrate-only

---

3. 写入环境并启动

编辑 /etc/biof3.env：

DATABASE_URL=postgres://...
BIOF3_PG_AUX_SQLITE_PATH=/opt/biof3-r-server/biof3-aux.sqlite
# 可选严格：未设 aux 则拒绝启动
# BIOF3_PG_STRICT=1

pm2 start biof3-r-server   # 或 pm2 restart
pm2 logs biof3-r-server --lines 50
# 应看到: PostgreSQL P0+P1 ... 与 P2 aux SQLite 路径

本机：

./deploy.sh --health

手工：登录、admin 游客权限、建单细胞项目、Copilot 新对话、管理台实时统计。

---

4. 回滚（仅当 PG 上几乎无新数据）

pm2 stop biof3-r-server
# 注释 DATABASE_URL、BIOF3_PG_AUX_SQLITE_PATH
# 确认 BIOF3_DB_PATH=/opt/biof3-r-server/biof3.db（或恢复 backup.sh 的 .gz）
pm2 start biof3-r-server

---

5. 切 PG 后日常备份

• SQLite：./deploy.sh --backup-r（保留至确认 PG 稳定）
• PostgreSQL：./scripts/backup-pg.sh（见脚本内 cron 示例）

---

6. 常见问题

现象	处理
能登录，无项目	未导 projects 或未开 DATABASE_URL；查 db:sqlite-to-pg 日志
Copilot 无历史	aux 路径错；应用 biof3-aux.sqlite 且含 copilot_* 表
启动报 page_views missing	npm run db:pg-migrate 未跑 002–004
admin 统计用户数为 0	analytics-users 未部署；users 应在 PG

---

7. 变更记录

日期	说明
2026-06-05	初版 runbook + cutover 脚本