28 KiB
28 KiB
卡若服务器管理系统 - 完整架构说明
一、系统定位
一句话定位：让AI写完代码之后，不需要任何人介入，系统自动把项目"变成一个在线网站"。
核心理念：
- 代码开发 = 由 TRAE / Cursor / AI 工具完成
- 本系统只负责：组合 + 自动化部署 + 上线 + 同步
二、整体架构图
┌─────────────────────────────────────────────────────────────────────────────┐
│ 卡若服务器管理系统 v2.0 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ 用户交互层 │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Cursor AI │ │ 终端命令 │ │ Python脚本 │ │ 配置文件 │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
│ └─────────┼────────────────┼────────────────┼────────────────┼─────────┘ │
│ │ │ │ │ │
│ └────────────────┴────────────────┴────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Skill 触发层 │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ 触发关键词: 服务器 / 宝塔 / 部署 / Node / SSL / DNS / MySQL │ │ │
│ │ │ 触发场景: 项目上线 / 状态检查 / 问题诊断 / 证书管理 │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ 核心组件层 │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 宝塔API │ │ SSH客户端 │ │ 环境修复 │ │ 服务器档案 │ │ │
│ │ │ (优先使用) │ │ (备选方案) │ │ (白名单等) │ │ (配置管理) │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
│ │ │ │ │ │ │ │
│ │ └────────────────┴────────────────┴────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ 功能插件层 │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 宝塔部署器 │ │ SSL证书管理 │ │阿里云DNS管理│ │ MySQL管理 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Nginx管理 │ │ 状态报告 │ │ 系统诊断 │ │ 项目修复 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ 服务器资源层 │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ 小型宝塔 │ │ 存客宝 │ │ kr宝塔 │ │ │
│ │ │ 42.194.232.22 │ │ 42.194.245.239 │ │ 43.139.27.93 │ │ │
│ │ │ 2核4G 5M │ │ 2核16G 50M │ │ 2核4G 5M │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ 外部服务 │ │ │
│ │ │ 阿里云DNS API | 腾讯云MySQL | GitHub/Coding 代码仓库 │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
三、核心流程图
3.1 标准部署流程
┌─────────────────────────────────────────────────────────────────────────────┐
│ Node项目一键部署流程 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ START │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 1. 读取部署配置 │ 配置文件: 部署配置/*.json │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 2. 修复API白名单 │ 环境修复.py → 确保本机IP在宝塔白名单 │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 3. 查询服务器状态│────▶│ 宝塔API: 系统统计 │ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 4. 探测空闲端口 │────▶│ SSH: netstat检查 │ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 5. 创建项目目录 │────▶│ 宝塔API: 创建目录 │ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 6. 上传代码压缩包│────▶│ SSH: scp上传 │ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 7. 解压代码 │────▶│ SSH: unzip │ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 8. 安装依赖 │────▶│ SSH: pnpm install│ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 9. 构建项目 │────▶│ SSH: pnpm build │ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │10. 修正启动端口 │────▶│ SSH: 修改package │ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │11. 宝塔添加项目 │────▶│ 宝塔API: create_project │ │
│ └────────┬─────────┘ │ (失败则需手动在面板添加) │ │
│ │ └──────────────────────────┘ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │12. 绑定域名 │────▶│ SSH: 调用宝塔内部│ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │13. 配置HTTPS │────▶│ SSH: 修改Nginx │ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │14. 健康检查 │ │
│ │ - 端口监听? │ │
│ │ - HTTP 200? │ │
│ │ - HTTPS 200? │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ SUCCESS │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 输出部署报告 │ │
│ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
3.2 问题诊断流程
┌─────────────────────────────────────────────────────────────────────────────┐
│ 问题诊断流程 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 用户报告问题 │
│ │ │
│ ▼ │
│ ┌─────────────────┐ 否 ┌─────────────────────────────────────────┐ │
│ │ 能连接服务器？ │─────────▶│ 检查项: │ │
│ └───────┬─────────┘ │ - SSH连接是否正常 │ │
│ │是 │ - 宝塔面板是否能访问 │ │
│ │ │ - API白名单是否包含本机IP │ │
│ ▼ └─────────────────────────────────────────┘ │
│ ┌─────────────────┐ 否 ┌─────────────────────────────────────────┐ │
│ │ 项目端口监听？ │─────────▶│ 检查项: │ │
│ └───────┬─────────┘ │ - PM2进程是否运行 │ │
│ │是 │ - 宝塔面板项目状态 │ │
│ │ │ - npm start是否报错 │ │
│ ▼ │ - 端口是否被其他进程占用 │ │
│ ┌─────────────────┐ 否 └─────────────────────────────────────────┘ │
│ │ Nginx配置正确？ │─────────▶│ 检查项: │ │
│ └───────┬─────────┘ │ - nginx -t 语法检查 │ │
│ │是 │ - server_name是否正确 │ │
│ │ │ - proxy_pass端口是否正确 │ │
│ ▼ │ - 是否有重复配置文件 │ │
│ ┌─────────────────┐ 否 └─────────────────────────────────────────┘ │
│ │ SSL证书有效？ │─────────▶│ 检查项: │ │
│ └───────┬─────────┘ │ - 证书是否过期 │ │
│ │是 │ - 证书路径是否正确 │ │
│ │ │ - 是否为通配符证书 │ │
│ ▼ └─────────────────────────────────────────┘ │
│ ┌─────────────────┐ 否 ┌─────────────────────────────────────────┐ │
│ │ DNS解析正确？ │─────────▶│ 检查项: │ │
│ └───────┬─────────┘ │ - dig查询A记录 │ │
│ │是 │ - 阿里云DNS控制台 │ │
│ │ │ - 本地DNS缓存 │ │
│ ▼ │ - 是否被代理劫持 │ │
│ ┌─────────────────┐ └─────────────────────────────────────────┘ │
│ │ 服务器内部正常 │ │
│ │ 检查客户端网络 │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
四、文件结构说明
服务器管理/
├── .codex/skills/karuo-server-manager/ # Skill 目录
│ ├── SKILL.md # 主文件（触发条件+核心流程）
│ ├── references/ # 参考文档
│ │ ├── 宝塔API接口文档.md
│ │ ├── 端口配置表.md
│ │ ├── 常见问题手册.md
│ │ └── 部署配置模板.md
│ ├── scripts/ # 快捷脚本
│ │ ├── 快速检查服务器.py
│ │ ├── 一键部署.py
│ │ └── SSL证书检查.py
│ └── assets/ # 资源文件
│ └── 系统架构说明.md
│
├── .cursor/rules/serverconnect.mdc # Cursor规则文件（凭证+规范）
│
├── 核心组件/ # 核心功能库
│ ├── SSH客户端.py
│ ├── 宝塔API.py
│ ├── 服务器档案.py
│ ├── 环境修复.py
│ └── 腾讯云MySQL管理.py
│
├── 功能插件/ # 独立功能模块
│ ├── MySQL数据库分析.py
│ ├── MySQL自动清理.py
│ ├── Nginx管理器.py
│ ├── Node管理器.py
│ ├── SSL证书管理器.py
│ ├── 宝塔中控.py
│ ├── 宝塔部署器.py
│ ├── 状态报告生成.py
│ ├── 系统诊断.py
│ ├── 阿里云DNS管理器.py
│ └── 项目深度修复.py
│
├── 部署配置/ # JSON配置文件
│ ├── soul_部署配置.json
│ ├── zhiji_部署配置.json
│ └── ...
│
├── 状态报告/ # 生成的报告
│ └── *.html
│
├── 开发文档/ # 开发文档
│ ├── 服务器管理插件系统总览.md
│ ├── 宝塔API接口文档.md
│ └── ...
│
└── 配置.py # 全局配置
五、使用规范
5.1 操作优先级
- 优先使用宝塔API - 稳定、可追溯
- 备选使用SSH - 用于API无法完成的操作
- 必要时手动操作 - 如添加Node项目到宝塔面板
5.2 安全规范
- ❌ 不在代码中硬编码密码
- ❌ 不执行危险命令（reboot, rm -rf /等）
- ❌ 不使用独立PM2（避免与宝塔冲突）
- ✅ 操作前先检查服务器状态
- ✅ 操作后验证结果
- ✅ 生成操作报告
5.3 输出规范
每次操作完成后，必须输出：
- 操作结果（成功/失败）
- 关键信息（端口、域名、访问地址）
- 验证结果（端口监听、HTTP响应）
- 后续操作建议