# scripts —— 运维与开发脚本

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

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

## 快速开始

```bash
# 本地开发（推荐）：首次运行会自动建 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`，
   否则调用方会一直阻塞。