From b0de930324493cf8d5cc4c94ce6b28cd0de497dd Mon Sep 17 00:00:00 2001 From: yumoqing Date: Wed, 29 Apr 2026 13:28:03 +0800 Subject: [PATCH] docs: update DEPLOY.md for automated one-step build process --- DEPLOY.md | 258 ++++++++++++++++++------------------------------------ 1 file changed, 83 insertions(+), 175 deletions(-) diff --git a/DEPLOY.md b/DEPLOY.md index f6c99f0..d6c8f29 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -2,120 +2,79 @@ ## 1. 环境准备 -### 1.1 系统要求 - Python 3.10+ -- MySQL 5.7+ +- MySQL 5.7+（需有 CREATE DATABASE 权限的管理员账号） - Git -### 1.2 克隆所有仓库 +## 2. 一键部署 + +只需克隆主应用并运行 build.sh，其余模块自动克隆、数据库自动配置： ```bash -mkdir -p ~/repos && cd ~/repos - -# 引用模块（5个，绝对不能修改） -git clone git@git.opencomputing.cn:yumoqing/apppublic.git -git clone git@git.opencomputing.cn:yumoqing/sqlor.git -git clone git@git.opencomputing.cn:yumoqing/ahserver.git -git clone git@git.opencomputing.cn:yumoqing/appbase.git -git clone git@git.opencomputing.cn:yumoqing/rbac.git - -# CRM业务模块（6个） -git clone git@git.opencomputing.cn:yumoqing/customer_management.git -git clone git@git.opencomputing.cn:yumoqing/opportunity_management.git -git clone git@git.opencomputing.cn:yumoqing/contract_management.git -git clone git@git.opencomputing.cn:yumoqing/financial_management.git -git clone git@git.opencomputing.cn:yumoqing/workflow_approval.git -git clone git@git.opencomputing.cn:yumoqing/unified_dashboard.git - -# 主应用 git clone git@git.opencomputing.cn:yumoqing/integrated_crm_app.git -``` - -## 2. 构建应用 - -```bash -cd ~/repos/integrated_crm_app +cd integrated_crm_app chmod +x build.sh ./build.sh ``` -构建脚本会完成： +构建脚本会自动完成： 1. 创建虚拟环境（py3/） -2. 安装核心依赖（apppublic、sqlor、ahserver） -3. 链接本地业务模块到 pkgs/ -4. 生成数据库 DDL（integrated_crm_app_schema.sql） +2. 安装核心依赖 +3. 克隆所有 11 个模块到 pkgs/（5个引用模块 + 6个业务模块） +4. 生成数据库 DDL 和 CRUD UI 5. 创建 wwwroot 符号链接 -6. 生成 start.sh / stop.sh +6. **交互式配置数据库**（host、port、用户名、密码） +7. 自动创建数据库、导入表结构 +8. 生成 config.json（密码自动 AES 加密） +9. 自动初始化权限（角色 + 权限映射） +10. 生成 start.sh / stop.sh -## 3. 数据库初始化 +### 2.1 数据库配置提示 + +运行 build.sh 时会依次询问： + +``` +MySQL host [localhost]: # 直接回车用默认 +MySQL port [3306]: # 直接回车用默认 +MySQL admin user [root]: # 有CREATE DATABASE权限的管理员 +MySQL admin password: # 管理员密码（不显示） +CRM database name [crm_db]: # 直接回车用默认 +CRM database user [hermes]: # 应用使用的数据库用户 +CRM database password: # 该用户密码（不显示） +``` + +> rbac 和所有业务模块共用同一个数据库，不会创建独立数据库。 + +## 3. 启动应用 -### 3.1 创建数据库 ```bash -mysql -u root -p -e "CREATE DATABASE crm_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" -mysql -u root -p -e "CREATE DATABASE rbac CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" +./start.sh # 默认端口 8080 +./start.sh 9999 # 指定端口 ``` -### 3.2 导入表结构 +访问：`http://localhost:8080/main/login.ui` + +## 4. 创建管理员用户 + +首次使用需注册并分配超级管理员角色： + +1. 访问 `http://localhost:8080/user/register.ui` 注册第一个用户 +2. 为该用户分配 `admin_superuser` 角色： + +```sql +mysql -u crm_user -p crm_db +INSERT INTO userroles (userid, roleid) VALUES ('你的用户ID', 'admin_superuser'); +``` + +## 5. 停止应用 + ```bash -# CRM业务表 -mysql -u root -p crm_db < ~/repos/integrated_crm_app/integrated_crm_app_schema.sql - -# RBAC表（rbac模块自带） -cd ~/repos/rbac -source ~/repos/integrated_crm_app/py3/bin/activate -python -c " -from appPublic.jsonConfig import getConfig -from appPublic.dictObject import DictObject -from sqlor.dbpools import DBPools -from rbac import load_rbac -import os -os.chdir(os.path.expanduser('~/repos/rbac')) -config = getConfig('.', {'workdir': '.'}) -db_config = {} -for k, v in config.databases.items(): - db_config[k] = DictObject(driver=v['driver'], kwargs=DictObject(**v['kwargs'])) -DBPools(db_config) -from rbac.rbac_tables import init_database -init_database() -" +./stop.sh ``` -### 3.3 创建RBAC默认数据 -RBAC模块需要在数据库中初始化： -- 一个超级管理员用户 -- 初始机构（orgtype） +## 6. 权限体系 -可通过 rbac 自带的注册功能完成，或运行 RBAC 的初始化脚本。 - -## 4. 配置数据库连接 - -编辑 `~/repos/integrated_crm_app/conf/config.json`： - -```json -{ - "password_key": "!@#$%^&*(*&^%$QWERTYUIqwertyui234567", - "databases": { - "crm_db": { - "driver": "mysql", - "kwargs": { - "host": "localhost", - "port": 3306, - "user": "你的MySQL用户名", - "password": "加密后的密码", - "db": "crm_db", - "charset": "utf8mb4" - } - } - } -} -``` - -> 注意：password 需要使用 apppublic 的加密工具加密，格式为 `apppublic.aes.encrypt(明文密码)` - -## 5. 权限初始化 - -### 5.1 角色定义 -CRM是**单业主机构**系统，所有角色属于同一机构内部： +### 6.1 角色定义（单业主机构） | 角色ID | 名称 | 说明 | |--------|------|------| @@ -127,85 +86,20 @@ CRM是**单业主机构**系统，所有角色属于同一机构内部： | finance_clerk | 财务出纳 | 收款登记、付款处理 | | admin_superuser | 超级用户 | 全部权限 | -### 5.2 执行权限初始化 +### 6.2 注意事项 -```bash -cd ~/repos/integrated_crm_app -source py3/bin/activate -python app/init_permissions.py -``` +- 角色 ID 使用**下划线**（如 `sales_manager`），**不能用点号**，因为前端显示格式为 `机构类型.角色名称`（如 `sales.manager`） +- `any`、`logined` 是约定角色，rbac 模块硬编码检查，必须用固定 ID +- rbac 自带完整登录注册功能（`pkgs/rbac/wwwroot/user/`），不要创建冗余文件 -该脚本会： -1. 创建约定角色（any、logined） -2. 创建定义的角色（sales_manager 等） -3. 扫描各模块 wwwroot 注册路径权限 -4. 根据 `app/perm_config.py` 中的 PERMISSION_MATRIX 授予角色权限 -5. 注册 CRUD 路径 - -### 5.3 约定角色说明 - -rbac 模块的 `userperm.py` 硬编码检查特殊角色 ID： -```python -if r.id == 'anonymous': k = 'anonymous' -elif r.id == 'any': k = 'any' -elif r.id == 'logined': k = 'logined' -``` - -因此 `any`、`logined` 必须使用固定字符串作为 ID，**不能用 getID() 随机生成**。 - -### 5.4 业务角色ID命名 - -业务角色 ID 使用**下划线**（如 `sales_manager`），**不能用点号**，因为前端显示格式为 `机构类型.角色名称`（如 `sales.manager`）。 - -## 6. 创建初始用户 - -通过 rbac 自带的注册功能创建用户： - -``` -访问 http://localhost:8080/user/register.ui -``` - -创建第一个用户后，通过数据库或 rbac 管理界面为其分配角色： - -```sql --- 将用户分配给 admin_superuser 角色 -INSERT INTO userroles (userid, roleid) -VALUES ('你的用户ID', 'admin_superuser'); -``` - -## 7. 启动应用 - -```bash -cd ~/repos/integrated_crm_app -./start.sh -``` - -默认端口 8080，可通过参数修改： - -```bash -python app/integrated_crm_app.py --port 9999 --root wwwroot/ -``` - -访问：`http://localhost:8080/main/login.ui` - -## 8. 停止应用 - -```bash -./stop.sh -# 或 -pkill -f "integrated_crm_app.py" -``` - -## 9. 模块引用规则 +## 7. 模块引用规则 | 类别 | 模块 | 规则 | |------|------|------| | 引用模块 | apppublic, sqlor, ahserver, appbase, rbac | **绝对不能修改** | | 业务模块 | customer_management 等 6 个 | 遵循 module-development-spec | -rbac 自带完整的登录注册功能（`rbac/wwwroot/user/`），开发时直接引用，**不要创建冗余的登录注册文件**。 - -## 10. 目录结构 +## 8. 目录结构 ``` integrated_crm_app/ @@ -214,10 +108,10 @@ integrated_crm_app/ │ ├── perm_config.py # 权限配置（角色+权限矩阵） │ └── init_permissions.py # 权限初始化脚本 ├── conf/ -│ └── config.json # 应用配置 +│ └── config.json # 应用配置（build.sh 自动生成） ├── wwwroot/ │ ├── main/ # 主页面 -│ ├── rbac/ # 用户管理（symlink） +│ ├── rbac/ # 用户管理（symlink → pkgs/rbac/wwwroot） │ ├── customer_management/ # 客户管理（symlink） │ ├── opportunity_management/ # 商机管理（symlink） │ ├── contract_management/ # 合同管理（symlink） @@ -225,14 +119,27 @@ integrated_crm_app/ │ ├── workflow_approval/ # 审批管理（symlink） │ ├── unified_dashboard/ # 仪表盘（symlink） │ └── bricks/ # 前端框架（symlink） -├── pkgs/ # 模块链接 -├── py3/ # 虚拟环境 +├── pkgs/ # 模块目录（build.sh 自动克隆） +│ ├── apppublic/ +│ ├── sqlor/ +│ ├── ahserver/ +│ ├── appbase/ +│ ├── rbac/ +│ ├── customer_management/ +│ ├── opportunity_management/ +│ ├── contract_management/ +│ ├── financial_management/ +│ ├── workflow_approval/ +│ └── unified_dashboard/ +├── py3/ # 虚拟环境（build.sh 自动创建） ├── logs/ # 日志 ├── files/ # 文件存储 -└── build.sh # 构建脚本 +├── build.sh # 一键构建脚本 +├── start.sh # 启动脚本（build.sh 自动生成） +└── stop.sh # 停止脚本（build.sh 自动生成） ``` -## 11. 故障排查 +## 9. 故障排查 ### 端口被占用 ```bash @@ -241,10 +148,11 @@ kill -9 ``` ### 数据库连接失败 -```bash -cd ~/repos/integrated_crm_app -python test_db_conn.py -``` +检查 `conf/config.json` 中的数据库配置是否正确。 ### 权限初始化失败 -检查 rbac 数据库中的 role、permission、rolepermission 表是否正确创建。 +重新运行： +```bash +source py3/bin/activate +python app/init_permissions.py +```