311 lines
28 KiB
Markdown
311 lines
28 KiB
Markdown
# 卡若服务器管理系统 - 完整架构说明
|
||
|
||
## 一、系统定位
|
||
|
||
**一句话定位**：让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. 后续操作建议
|