# 🛠️ FF AI Workspace 脚本工具集 > **版本**: v6.0.0 > **更新日期**: 2024-12-25 > **支持平台**: macOS, Linux, Windows --- ## 📋 目录 - [脚本总览](#-脚本总览) - [目录结构](#-目录结构) - [开发环境](#-开发环境) - [生产环境](#-生产环境) - [后端工具](#-后端工具) - [文档管理](#-文档管理) - [快速参考](#-快速参考) --- ## 📁 目录结构 ``` scripts/ ├── README.md # 本文件 ├── dev/ # 开发环境脚本 │ ├── dev.sh # macOS/Linux 统一开发入口 ⭐ │ ├── dev.ps1 # Windows PowerShell 入口 ⭐ │ ├── dev.bat # Windows 批处理包装器 │ └── setup-worktree.sh # 创建并初始化 worktree ⭐ ├── deploy/ # 生产环境部署 │ ├── setup-production.sh # 服务器初始化（一次性） │ ├── deploy-production.sh # 应用部署（常用）⭐ │ ├── docker-manage.sh # Docker 管理 ⭐ │ └── deploy-uat.sh # UAT 环境部署 ├── backend/ # 后端专用工具 │ ├── init/ # 初始化脚本 │ │ ├── init-permissions.ts # 初始化权限 │ │ ├── init-itadmin.ts # 创建 IT 管理员 │ │ └── init-notification-templates.ts # 初始化通知模板 │ ├── data/ # 数据管理 │ │ ├── check-manager-data.ts # 检查管理者数据 │ │ ├── clean-org-members.ts # 清理组织成员 │ │ └── clear-departments.ts # 清空部门 │ └── test/ # 测试工具 │ └── test-cors-config.ts # 测试 CORS 配置 ├── env/ # 环境配置 │ ├── setup-env.sh # 设置环境变量 ⭐ │ ├── validate-env.sh # 验证环境变量 │ └── README.md # 📄 环境脚本说明 └── check-test-assertions.py # E2E 测试断言检查工具 ``` --- ## 🔥 脚本总览 ### 按使用频率分类 | 频率 | 脚本 | 用途 | 位置 | |------|------|------|------| | **每天** | `dev.sh` / `dev.ps1` | 统一开发入口 | `scripts/dev/` | | **按需** | `setup-worktree.sh` | 创建并初始化并行开发 worktree | `scripts/dev/` | | **每天** | `docker-manage.sh` | Docker 管理 | `scripts/deploy/` | | **每周** | `deploy-production.sh` | 应用部署 | `scripts/deploy/` | | **首次** | `setup-production.sh` | 服务器初始化 | `scripts/deploy/` | | **首次** | `init-*.ts` | 数据初始化 | `scripts/backend/init/` | | **按需** | `data/*.ts` | 数据管理 | `scripts/backend/data/` | | **按需** | `env/*.sh` | 环境配置 | `scripts/env/` | | **工具** | `check-test-assertions.py` | E2E 断言检查 | `scripts/` | --- ## 🎯 开发环境 ### `dev.sh` / `dev.ps1` - 统一开发入口 ⭐⭐⭐ **所有日常开发操作的统一入口** #### 快速开始 ```bash # macOS / Linux bash scripts/dev/dev.sh start # Windows (PowerShell - 推荐) .\scripts\dev\dev.ps1 start # Windows (批处理 - 需要 Git Bash) scripts\dev\dev.bat start ``` #### 推荐：添加别名 ```bash # macOS / Linux echo "alias dev='bash $(pwd)/scripts/dev/dev.sh'" >> ~/.zshrc source ~/.zshrc # 然后就可以简单使用 dev start dev stop dev status ``` #### 核心功能 ##### 1. 服务管理 ```bash dev start # 启动所有服务（Docker + 前后端） dev stop # 停止所有服务 dev restart # 重启所有服务 dev restart --backend # 仅重启后端 dev restart --frontend # 仅重启前端 dev status # 查看服务状态 ``` ##### 2. Docker 管理 ```bash dev docker:start # 启动 Docker 服务 dev docker:start --all # 启动所有 Docker 服务（包含监控） dev docker:stop # 停止 Docker 服务 dev docker:ps # 查看运行中的容器 dev docker:logs # 查看 Docker 日志 dev docker:clean # 删除容器及数据卷 ⚠️ ``` ##### 3. 数据库管理 ```bash dev db:init # 初始化数据库（首次使用）⭐ dev db:migrate # 运行数据库迁移 dev db:reset # 重置数据库 ⚠️ dev db:seed # 填充测试数据 dev db:studio # 打开 Prisma Studio dev db:backup # 备份数据库 dev db:init-permissions # 初始化权限数据 ``` ##### 4. 清理功能 ```bash dev clean # 清理构建缓存 dev clean --all # 完全清理（包含 node_modules）⚠️ dev clean --docker # 清理 Docker 资源 ⚠️ dev clean --deep # 交互式深度清理 ✨ ``` ##### 5. 其他功能 ```bash dev logs # 查看应用日志 dev logs --follow # 实时查看日志 dev health # API 健康检查 dev admin:create # 创建管理员用户 dev check # 检查环境配置 dev version # 查看版本信息 dev help # 查看帮助 ``` #### 交互式菜单 ```bash # 启动交互式菜单（无参数） bash scripts/dev/dev.sh ``` --- ## 🚀 生产环境 ### 首次部署流程 #### 步骤 1: 服务器初始化（一次性） ```bash # 1. 登录服务器并克隆项目 ssh root@your-server-ip git clone cd workspace # 2. 运行初始化脚本 sudo bash scripts/deploy/setup-production.sh ``` **功能：** 安装 Docker、Node.js、PM2、Nginx、Certbot 等基础环境 #### 步骤 2: 启动 Docker 服务 ```bash # 启动基础服务（PostgreSQL + Redis） bash scripts/deploy/docker-manage.sh start basic # 或启动完整服务（+ Temporal + MinIO） bash scripts/deploy/docker-manage.sh start full ``` #### 步骤 3: 部署应用 ```bash # 完整部署 bash scripts/deploy/deploy-production.sh all ``` ### 后续更新流程 ```bash # 代码更新时（最常用） bash scripts/deploy/deploy-production.sh all # 或分别部署 bash scripts/deploy/deploy-production.sh backend # 仅后端 bash scripts/deploy/deploy-production.sh frontend # 仅前端 # 回滚 bash scripts/deploy/deploy-production.sh rollback ``` ### Docker 管理 ```bash # 查看状态 bash scripts/deploy/docker-manage.sh status # 查看日志 bash scripts/deploy/docker-manage.sh logs # 所有服务 bash scripts/deploy/docker-manage.sh logs postgres # 指定服务 # 重启服务 bash scripts/deploy/docker-manage.sh restart # 备份数据库 ⭐ bash scripts/deploy/docker-manage.sh backup # 停止服务 bash scripts/deploy/docker-manage.sh stop ``` --- ## 🔧 后端工具 ### 初始化脚本 (`scripts/backend/init/`) ```bash cd backend # 初始化权限系统 npm run init:permissions # 创建 IT 管理员账号 npm run init:itadmin # 初始化通知模板 npm run init:notification-templates ``` ### 数据管理 (`scripts/backend/data/`) ```bash cd backend # 清理组织成员数据 npm run clean:org-members # 清空部门数据 npm run clear:departments # 检查管理者数据完整性 npx ts-node ../scripts/backend/data/check-manager-data.ts ``` --- ## 📖 快速参考 ### 开发环境常用命令 ```bash # 首次启动 bash scripts/dev/dev.sh db:init # 初始化数据库 bash scripts/dev/dev.sh start # 启动所有服务 # 日常开发 bash scripts/dev/dev.sh restart --backend # 重启后端 bash scripts/dev/dev.sh logs --follow # 查看日志 bash scripts/dev/dev.sh db:studio # 打开数据库管理界面 # 遇到问题 bash scripts/dev/dev.sh stop # 停止所有服务 bash scripts/dev/dev.sh clean --deep # 深度清理 bash scripts/dev/dev.sh db:init # 重新初始化 bash scripts/dev/dev.sh start # 重新启动 ``` ### 生产环境常用命令 ```bash # 首次部署（按顺序执行） sudo bash scripts/deploy/setup-production.sh # 1. 初始化服务器 bash scripts/deploy/docker-manage.sh start full # 2. 启动 Docker bash scripts/deploy/deploy-production.sh all # 3. 部署应用 # 代码更新 bash scripts/deploy/deploy-production.sh all # 日常运维 bash scripts/deploy/docker-manage.sh status # 查看状态 bash scripts/deploy/docker-manage.sh logs # 查看日志 bash scripts/deploy/docker-manage.sh backup # 备份数据库 ``` ### 端口说明 | 服务 | 开发环境 | 生产环境 | 说明 | |------|----------|----------|------| | 前端 | 3000 | 6010 | Next.js | | 后端 API | 3001 | 6011 | NestJS | | PostgreSQL | 5432 | 6001 | 数据库 | | Redis | 6379 | 6002 | 缓存 | | Temporal | 7233 | 6003 | 工作流引擎 | | Temporal UI | 8080 | 6004 | Temporal 管理界面 | | MinIO | 9000 | 6006 | 对象存储 | | MinIO Console | 9001 | 6007 | MinIO 管理界面 | --- ## ❓ 常见问题 ### 1. 找不到脚本文件 **问题**：运行 `npm run init:permissions` 失败 **解决**：脚本已迁移到统一目录，确保使用新路径： ```bash # 新路径（自动） cd backend npm run init:permissions # 或手动执行 npx ts-node ../scripts/backend/init/init-permissions.ts ``` ### 2. 首次启动失败 ```bash # 检查 Docker 是否运行 docker ps # 重新初始化数据库 bash scripts/dev/dev.sh db:init # 查看详细日志 bash scripts/dev/dev.sh logs --follow ``` ### 3. 端口被占用 ```bash # macOS/Linux - 查找并杀死占用端口的进程 lsof -ti:3000 | xargs kill -9 # 前端 lsof -ti:3001 | xargs kill -9 # 后端 # Windows - 查找并杀死进程 netstat -ano | findstr :3000 taskkill /PID /F ``` --- ## 🔄 从旧版本迁移 ### v6.0.0 更新内容 ✅ **脚本统一管理** - 所有脚本移至根目录 `scripts/` ✅ **按功能分类** - 清晰的目录结构（dev/deploy/backend/docs/refactor） ✅ **重构脚本归档** - 历史重构脚本保留在 `refactor/` 目录 ✅ **路径更新** - backend/package.json 脚本路径已更新 ### 路径对照表 | 旧路径 | 新路径 | |--------|--------| | `backend/scripts/init-*.ts` | `scripts/backend/init/init-*.ts` | | `backend/scripts/clean-*.ts` | `scripts/backend/data/clean-*.ts` | | `frontend/scripts/*.js` | `scripts/refactor/frontend/*.js` | | `scripts/dev.sh` | `scripts/dev/dev.sh` | | `scripts/deploy-production.sh` | `scripts/deploy/deploy-production.sh` | --- ## 📝 更新日志 ### v6.0.0 (2024-12-25) - ✅ 统一所有脚本到 `scripts/` 目录 - ✅ 按功能分类：dev/deploy/backend/docs/refactor - ✅ 重构脚本归档到 `refactor/` 子目录 - ✅ 更新所有脚本引用路径 - ✅ 删除旧的 `backend/scripts/` 和 `frontend/scripts/` - ✅ 创建统一的脚本文档 ### v5.0.0 (2025-11-27) - ✅ 清理并删除过时脚本 - ✅ 集成深度清理功能到 `dev.sh clean --deep` - ✅ 添加 Windows 批处理脚本 `dev.bat` - ✅ 更新生产环境脚本文档和注释 --- ## 🆘 获取帮助 ### 查看帮助 ```bash # 开发环境 bash scripts/dev/dev.sh help # 生产环境 bash scripts/deploy/deploy-production.sh help bash scripts/deploy/docker-manage.sh help ``` ### 报告问题 1. 查看日志：`bash scripts/dev/dev.sh logs` 2. 检查状态：`bash scripts/dev/dev.sh status` 3. 收集信息：`bash scripts/dev/dev.sh version` 4. 创建 Issue 并附上以上信息 --- **维护者**: FF AI Workspace 开发团队 **问题反馈**: 请创建 Issue **贡献**: 欢迎提交 PR --- **祝开发愉快！** 🚀