# 卡若服务器管理系统 - 完整架构说明 ## 一、系统定位 **一句话定位**：让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 操作优先级 1. **优先使用宝塔API** - 稳定、可追溯 2. **备选使用SSH** - 用于API无法完成的操作 3. **必要时手动操作** - 如添加Node项目到宝塔面板 ### 5.2 安全规范 - ❌ 不在代码中硬编码密码 - ❌ 不执行危险命令（reboot, rm -rf /等） - ❌ 不使用独立PM2（避免与宝塔冲突） - ✅ 操作前先检查服务器状态 - ✅ 操作后验证结果 - ✅ 生成操作报告 ### 5.3 输出规范 每次操作完成后，必须输出： 1. 操作结果（成功/失败） 2. 关键信息（端口、域名、访问地址） 3. 验证结果（端口监听、HTTP响应） 4. 后续操作建议