232 lines
5.8 KiB
Markdown
232 lines
5.8 KiB
Markdown
# 系统初始化执行手册
|
||
|
||
本手册用于在后端服务器上初始化 ForgeFlow ERP 客户数据库。请注意：重置模式会清理目标数据库中的业务数据，正式执行前必须再次确认目标库、备份路径和是否清理实体文件。
|
||
|
||
## 适用场景
|
||
|
||
全新初始化模式 `fresh` 适用于全新客户数据库或空数据库结构。它会创建数据库、创建 ERP 与小程序相关全部表，并写入最小系统骨架。
|
||
|
||
重置初始化模式 `reset` 适用于已经部署过、但需要正式启用前清理测试数据的数据库。它会先执行 MySQL 备份，再清空业务数据、主数据、人员账号、小程序数据，并重建最小系统骨架。
|
||
|
||
默认不会删除 PDF、照片等实体文件。只有显式增加 `--delete-files` 时，才会清理系统管理范围内的文件目录内容。
|
||
|
||
## 执行前检查
|
||
|
||
执行前先进入后端目录并激活虚拟环境：
|
||
|
||
```bash
|
||
cd /home/souplearn/ERP/ForgeFlow-ERP/backend
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
确认 `.env` 中数据库配置指向正确目标：
|
||
|
||
```bash
|
||
grep -E "MYSQL_HOST|MYSQL_PORT|MYSQL_DATABASE|MYSQL_USER" .env
|
||
```
|
||
|
||
确认后端能连接数据库：
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8000/api/system/health | python3 -m json.tool
|
||
```
|
||
|
||
## 全新数据库初始化
|
||
|
||
新客户全新部署时使用全新初始化模式 `fresh`：
|
||
|
||
```bash
|
||
python scripts/system_initialize.py fresh \
|
||
--company-name 百华 \
|
||
--admin-name 超级管理员 \
|
||
--admin-phone 13800000000 \
|
||
--admin-password '正式密码' \
|
||
--smart-operation-report on
|
||
```
|
||
|
||
执行成功后，命令行会输出：
|
||
|
||
```text
|
||
mode=fresh
|
||
database=<数据库地址>:<端口>/<数据库名>
|
||
backup_path=
|
||
summary_path=
|
||
admin_username=13800000000
|
||
```
|
||
|
||
## 已有测试库重置
|
||
|
||
已有测试数据、需要正式启用前清理时使用重置初始化模式 `reset`。该模式必须显式传入确认参数 `--confirm-reset`：
|
||
|
||
```bash
|
||
python scripts/system_initialize.py reset \
|
||
--company-name 百华 \
|
||
--admin-name 超级管理员 \
|
||
--admin-phone 13800000000 \
|
||
--admin-password '正式密码' \
|
||
--smart-operation-report on \
|
||
--confirm-reset
|
||
```
|
||
|
||
执行成功后，命令行会输出：
|
||
|
||
```text
|
||
mode=reset
|
||
database=<数据库地址>:<端口>/<数据库名>
|
||
backup_path=/path/to/system_init_backup_<timestamp>.sql
|
||
summary_path=/path/to/system_init_summary_<timestamp>.json
|
||
admin_username=13800000000
|
||
```
|
||
|
||
备份和执行摘要默认写入：
|
||
|
||
```text
|
||
outputs/cleanup_backups/
|
||
```
|
||
|
||
## 可选文件清理
|
||
|
||
默认重置初始化只清数据库记录，不删除实体文件。
|
||
|
||
如确实需要同时清理系统托管的历史文件，才增加 `--delete-files`：
|
||
|
||
```bash
|
||
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` 只会删除以下目录中的子文件和子目录，不会删除目录本身：
|
||
|
||
```text
|
||
outputs/document_archives
|
||
outputs/document_archive_batches
|
||
backend/uploads/logistics
|
||
```
|
||
|
||
## 初始化后验证
|
||
|
||
先验证 API 健康状态：
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8000/api/system/health | python3 -m json.tool
|
||
```
|
||
|
||
再验证核心数据状态。为了避免密码出现在命令行参数中，使用临时 MySQL 配置文件：
|
||
|
||
```bash
|
||
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"
|
||
```
|
||
|
||
预期结果：
|
||
|
||
```text
|
||
customer_count = 0
|
||
supplier_count = 0
|
||
stock_lot_count = 0
|
||
sales_order_count = 0
|
||
admin_count = 1
|
||
```
|
||
|
||
然后用初始化账号登录 ERP：
|
||
|
||
```text
|
||
账号：初始化时填写的管理员手机号
|
||
密码：初始化时填写的管理员密码
|
||
```
|
||
|
||
## 执行摘要检查
|
||
|
||
重置初始化执行后检查 JSON 格式的执行摘要：
|
||
|
||
```bash
|
||
python3 -m json.tool outputs/cleanup_backups/system_init_summary_<timestamp>.json
|
||
```
|
||
|
||
重点确认：
|
||
|
||
```text
|
||
mode
|
||
database
|
||
backup_path
|
||
summary_path
|
||
counts_before
|
||
counts_after
|
||
seeded.admin_username
|
||
```
|
||
|
||
如果使用了 `--delete-files`，还应看到：
|
||
|
||
```text
|
||
seeded.deleted_file_count
|
||
seeded.deleted_dir_count
|
||
```
|
||
|
||
## 回滚方式
|
||
|
||
如果重置初始化后发现目标数据库选错，先停止相关服务，避免继续写入：
|
||
|
||
```bash
|
||
sudo systemctl stop forgeflow-backend
|
||
```
|
||
|
||
然后使用本次生成的备份 SQL 恢复：
|
||
|
||
```bash
|
||
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"
|
||
```
|
||
|
||
恢复完成后再启动服务：
|
||
|
||
```bash
|
||
sudo systemctl start forgeflow-backend
|
||
```
|
||
|
||
## 安全提醒
|
||
|
||
正式环境执行重置初始化前必须确认：
|
||
|
||
1. `.env` 中的 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_DATABASE` 是目标测试库或待初始化客户库。
|
||
2. 已经明确允许清理该库中的现有数据。
|
||
3. `outputs/cleanup_backups` 有足够磁盘空间保存备份。
|
||
4. 没有显式传入 `--delete-files` 时，不会删除 PDF、照片等实体文件。
|
||
5. 只有确认要清理实体文件时，才允许传入 `--delete-files`。
|
||
6. 执行后必须先保存备份 SQL，再做后续验收。
|