nex_docus/scripts/README.md

47 lines
2.3 KiB
Markdown
Raw Normal View History

2026-10-01 07:21:38 +00:00
# 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`,
否则调用方会一直阻塞。