nex_docus/scripts/README.md

scripts —— 运维与开发脚本

本目录是仓库内所有运维/开发脚本的唯一入口。业务代码使用的运行时脚本仍与代码同仓 （如 backend/scripts/，原因见其 README）。

脚本	用途	常用场景
start.sh	一键启动：检查依赖 → 准备虚拟环境/前端依赖 → 校验 MySQL/Redis → 初始化数据库 → 启动后端 + 前端（默认前台驻留，--daemon 后台常驻）	日常开发
stop.sh	停止 start.sh 启动的本地服务	日常开发
deploy.sh	Docker Compose 部署管理：init / start / stop / restart / status / logs / upgrade / backup / restore / uninstall	服务器部署与升级

快速开始

# 本地开发（推荐）：首次运行会自动建 venv、装依赖、初始化数据库
./scripts/start.sh

# 只启动某一侧
./scripts/start.sh --backend
./scripts/start.sh --frontend

# 只准备环境，不启动服务
./scripts/start.sh --install

# 启动后立即返回（服务后台常驻，适合放在脚本/CI 里；用 stop.sh 停止）
./scripts/start.sh --daemon

# Docker 部署
./scripts/start.sh --docker          # 等价于 ./scripts/deploy.sh start
./scripts/deploy.sh init             # 首次部署（生成 .env、建库、构建镜像）
./scripts/deploy.sh status           # 查看容器状态
./scripts/deploy.sh backup           # 备份数据库

约定

1. 不要 cd 进脚本目录执行：脚本通过 BASH_SOURCE 自行定位项目根目录， 因此可以在任意工作目录下用 ./scripts/xxx.sh 或绝对路径调用，行为一致。
2. 运行期产物放在 .run/（pid、日志），已被 .gitignore 排除。
3. 新增一次性脚本请先确认是否真的需要：数据库结构由 backend/app/core/migrations.py + backend/scripts/init_db.py 幂等维护， 不再新增散落各处的 *.sql 补丁。
4. 所有脚本使用 bash，以 set -euo pipefail 起手，输出使用统一的颜色前缀 （▸ 进行中 / ✓ 成功 / ! 警告 / ✗ 失败）。
5. start.sh 默认前台驻留（Ctrl+C 停止）；需要"启动完就返回"时必须用 --daemon， 否则调用方会一直阻塞。