tangxh/ForgeFlow-ERP

Fork 0

汤学会 e308a6a7f2 docs: add Chinese system initialization runbook

2026-06-15 00:16:08 +08:00

5.8 KiB

Raw Blame History

系统初始化执行手册

本手册用于在后端服务器上初始化 ForgeFlow ERP 客户数据库。请注意：重置模式会清理目标数据库中的业务数据，正式执行前必须再次确认目标库、备份路径和是否清理实体文件。

适用场景

全新初始化模式 fresh 适用于全新客户数据库或空数据库结构。它会创建数据库、创建 ERP 与小程序相关全部表，并写入最小系统骨架。

重置初始化模式 reset 适用于已经部署过、但需要正式启用前清理测试数据的数据库。它会先执行 MySQL 备份，再清空业务数据、主数据、人员账号、小程序数据，并重建最小系统骨架。

默认不会删除 PDF、照片等实体文件。只有显式增加 --delete-files 时，才会清理系统管理范围内的文件目录内容。

执行前检查

执行前先进入后端目录并激活虚拟环境：

cd /home/souplearn/ERP/ForgeFlow-ERP/backend
source .venv/bin/activate

确认 .env 中数据库配置指向正确目标：

grep -E "MYSQL_HOST|MYSQL_PORT|MYSQL_DATABASE|MYSQL_USER" .env

确认后端能连接数据库：

curl -s http://127.0.0.1:8000/api/system/health | python3 -m json.tool

全新数据库初始化

新客户全新部署时使用全新初始化模式 fresh：

python scripts/system_initialize.py fresh \
  --company-name 百华 \
  --admin-name 超级管理员 \
  --admin-phone 13800000000 \
  --admin-password '正式密码' \
  --smart-operation-report on

执行成功后，命令行会输出：

mode=fresh
database=<数据库地址>:<端口>/<数据库名>
backup_path=
summary_path=
admin_username=13800000000

已有测试库重置

已有测试数据、需要正式启用前清理时使用重置初始化模式 reset。该模式必须显式传入确认参数 --confirm-reset：

python scripts/system_initialize.py reset \
  --company-name 百华 \
  --admin-name 超级管理员 \
  --admin-phone 13800000000 \
  --admin-password '正式密码' \
  --smart-operation-report on \
  --confirm-reset

执行成功后，命令行会输出：

mode=reset
database=<数据库地址>:<端口>/<数据库名>
backup_path=/path/to/system_init_backup_<timestamp>.sql
summary_path=/path/to/system_init_summary_<timestamp>.json
admin_username=13800000000

备份和执行摘要默认写入：

outputs/cleanup_backups/

可选文件清理

默认重置初始化只清数据库记录，不删除实体文件。

如确实需要同时清理系统托管的历史文件，才增加 --delete-files：

python scripts/system_initialize.py reset \
  --company-name 百华 \
  --admin-name 超级管理员 \
  --admin-phone 13800000000 \
  --admin-password '正式密码' \
  --smart-operation-report on \
  --confirm-reset \
  --delete-files

--delete-files 只会删除以下目录中的子文件和子目录，不会删除目录本身：

outputs/document_archives
outputs/document_archive_batches
backend/uploads/logistics

初始化后验证

先验证 API 健康状态：

curl -s http://127.0.0.1:8000/api/system/health | python3 -m json.tool

再验证核心数据状态。为了避免密码出现在命令行参数中，使用临时 MySQL 配置文件：

MYSQL_DEFAULTS_FILE="$(mktemp)"
chmod 600 "$MYSQL_DEFAULTS_FILE"
cat > "$MYSQL_DEFAULTS_FILE" <<EOF
[client]
host=$MYSQL_HOST
port=$MYSQL_PORT
user=$MYSQL_USER
password=$MYSQL_PASSWORD
default-character-set=utf8mb4
EOF

mysql --defaults-extra-file="$MYSQL_DEFAULTS_FILE" "$MYSQL_DATABASE" -e "
SELECT COUNT(*) AS customer_count FROM md_customer;
SELECT COUNT(*) AS supplier_count FROM md_supplier;
SELECT COUNT(*) AS stock_lot_count FROM wh_stock_lot;
SELECT COUNT(*) AS sales_order_count FROM so_sales_order;
SELECT COUNT(*) AS admin_count FROM sys_user WHERE username='13800000000' AND is_super_admin=1;
"

rm -f "$MYSQL_DEFAULTS_FILE"

预期结果：

customer_count = 0
supplier_count = 0
stock_lot_count = 0
sales_order_count = 0
admin_count = 1

然后用初始化账号登录 ERP：

账号：初始化时填写的管理员手机号
密码：初始化时填写的管理员密码

执行摘要检查

重置初始化执行后检查 JSON 格式的执行摘要：

python3 -m json.tool outputs/cleanup_backups/system_init_summary_<timestamp>.json

重点确认：

mode
database
backup_path
summary_path
counts_before
counts_after
seeded.admin_username

如果使用了 --delete-files，还应看到：

seeded.deleted_file_count
seeded.deleted_dir_count

回滚方式

如果重置初始化后发现目标数据库选错，先停止相关服务，避免继续写入：

sudo systemctl stop forgeflow-backend

然后使用本次生成的备份 SQL 恢复：

MYSQL_DEFAULTS_FILE="$(mktemp)"
chmod 600 "$MYSQL_DEFAULTS_FILE"
cat > "$MYSQL_DEFAULTS_FILE" <<EOF
[client]
host=$MYSQL_HOST
port=$MYSQL_PORT
user=$MYSQL_USER
password=$MYSQL_PASSWORD
default-character-set=utf8mb4
EOF

mysql --defaults-extra-file="$MYSQL_DEFAULTS_FILE" "$MYSQL_DATABASE" < outputs/cleanup_backups/system_init_backup_<timestamp>.sql

rm -f "$MYSQL_DEFAULTS_FILE"

恢复完成后再启动服务：

sudo systemctl start forgeflow-backend

安全提醒

正式环境执行重置初始化前必须确认：

.env 中的 MYSQL_HOST、MYSQL_PORT、MYSQL_DATABASE 是目标测试库或待初始化客户库。
已经明确允许清理该库中的现有数据。
outputs/cleanup_backups 有足够磁盘空间保存备份。
没有显式传入 --delete-files 时，不会删除 PDF、照片等实体文件。
只有确认要清理实体文件时，才允许传入 --delete-files。
执行后必须先保存备份 SQL，再做后续验收。

5.8 KiB Raw Blame History Unescape Escape