mirror of
https://github.com/TheFunny/ArisuAutoSweeper
synced 2025-12-16 19:55:12 +00:00
322 lines
7.9 KiB
Markdown
322 lines
7.9 KiB
Markdown
# FastAPI WebUI Migration Guide
|
||
|
||
## 概述 / Overview
|
||
|
||
本项目的 WebUI 已重构为使用 FastAPI 作为后端，提供现代化的 REST API 架构，同时保持与原有 PyWebIO 界面一致的视觉风格。
|
||
|
||
The WebUI has been refactored to use FastAPI as the backend, providing a modern REST API architecture while maintaining a visual style consistent with the original PyWebIO interface.
|
||
|
||
## 主要变化 / Key Changes
|
||
|
||
### 新增功能 / New Features
|
||
|
||
1. **FastAPI 后端** / **FastAPI Backend**
|
||
- 完整的 REST API 支持
|
||
- 自动生成的 API 文档 (访问 `/docs`)
|
||
- WebSocket 支持实时日志流
|
||
- 更好的错误处理和验证
|
||
|
||
2. **分离的前后端架构** / **Separated Frontend/Backend Architecture**
|
||
- 后端: FastAPI (REST API)
|
||
- 前端: HTML/CSS/JavaScript
|
||
- 可以被多种客户端使用 (Web, Mobile, CLI)
|
||
|
||
3. **向后兼容** / **Backward Compatible**
|
||
- 原有的 PyWebIO 界面仍然可用
|
||
- 两个后端可以同时存在
|
||
|
||
### 架构对比 / Architecture Comparison
|
||
|
||
| 特性 / Feature | PyWebIO (原有) | FastAPI (新) |
|
||
|----------------|---------------|-------------|
|
||
| 启动命令 / Launch | `python gui.py` | `python gui_fastapi.py` |
|
||
| 架构 / Architecture | 单体应用 | 前后端分离 |
|
||
| API 访问 / API Access | 有限 | 完整 REST API |
|
||
| 实时更新 / Real-time | Session-based | WebSocket |
|
||
| 文档 / Documentation | 无 | 自动生成 (/docs) |
|
||
| 可扩展性 / Extensibility | 低 | 高 |
|
||
|
||
## 使用方法 / Usage
|
||
|
||
### 启动 FastAPI 后端 / Starting FastAPI Backend
|
||
|
||
```bash
|
||
# 使用默认配置
|
||
python gui_fastapi.py
|
||
|
||
# 指定主机和端口
|
||
python gui_fastapi.py --host 0.0.0.0 --port 23467
|
||
|
||
# 使用密码保护
|
||
python gui_fastapi.py --key your_password
|
||
```
|
||
|
||
### 启动原有 PyWebIO 后端 / Starting Original PyWebIO Backend
|
||
|
||
```bash
|
||
python gui.py
|
||
```
|
||
|
||
## API 端点 / API Endpoints
|
||
|
||
### 配置管理 / Configuration Management
|
||
|
||
```bash
|
||
# 获取所有实例列表
|
||
GET /api/config/instances
|
||
|
||
# 获取特定实例的配置
|
||
GET /api/config/{instance_name}
|
||
|
||
# 更新配置
|
||
POST /api/config/{instance_name}
|
||
Body: [{"path": "TaskName.GroupName.SettingName", "value": "new_value"}]
|
||
|
||
# 创建新实例
|
||
POST /api/config/create?name=new_instance©_from=template-aas
|
||
```
|
||
|
||
### 进程管理 / Process Management
|
||
|
||
```bash
|
||
# 获取所有进程状态
|
||
GET /api/process/
|
||
|
||
# 获取特定进程状态
|
||
GET /api/process/{instance_name}/status
|
||
|
||
# 启动进程
|
||
POST /api/process/{instance_name}/start
|
||
|
||
# 停止进程
|
||
POST /api/process/{instance_name}/stop
|
||
|
||
# 重启进程
|
||
POST /api/process/{instance_name}/restart
|
||
```
|
||
|
||
### 系统管理 / System Management
|
||
|
||
```bash
|
||
# 获取系统信息
|
||
GET /api/system/info
|
||
|
||
# 设置语言
|
||
POST /api/system/language
|
||
Body: {"language": "zh-CN"}
|
||
|
||
# 设置主题
|
||
POST /api/system/theme
|
||
Body: {"theme": "dark"}
|
||
|
||
# 检查更新
|
||
POST /api/system/update/check
|
||
|
||
# 执行更新
|
||
POST /api/system/update/run
|
||
```
|
||
|
||
### WebSocket
|
||
|
||
```javascript
|
||
// 连接到特定实例的日志流
|
||
const ws = new WebSocket('ws://localhost:23467/ws/logs/aas');
|
||
|
||
ws.onmessage = (event) => {
|
||
const data = JSON.parse(event.data);
|
||
console.log(data);
|
||
};
|
||
|
||
// 系统级 WebSocket
|
||
const sysWs = new WebSocket('ws://localhost:23467/ws/system');
|
||
```
|
||
|
||
## 前端界面 / Frontend Interface
|
||
|
||
### 布局 / Layout
|
||
|
||
新界面采用网格布局，分为四个主要区域：
|
||
|
||
The new interface uses a grid layout with four main areas:
|
||
|
||
1. **Header** (顶部) - 标题和状态指示器
|
||
2. **Aside** (左侧) - 实例导航
|
||
3. **Menu** (中左) - 功能菜单
|
||
4. **Content** (主要内容区) - 内容显示
|
||
|
||
### 样式 / Styling
|
||
|
||
前端复用了原有的 CSS 文件以保持一致的视觉风格：
|
||
|
||
The frontend reuses the original CSS files to maintain consistent styling:
|
||
|
||
- `assets/gui/css/alas.css` - 基础样式
|
||
- `assets/gui/css/alas-pc.css` - 桌面端样式
|
||
- `assets/gui/css/light-alas.css` - 浅色主题
|
||
- `assets/gui/css/dark-alas.css` - 深色主题
|
||
|
||
## 功能对比 / Feature Comparison
|
||
|
||
### 已实现 / Implemented ✅
|
||
|
||
- [x] 实例列表和选择
|
||
- [x] 进程控制 (启动/停止/重启)
|
||
- [x] 系统信息显示
|
||
- [x] 语言切换
|
||
- [x] 主题切换
|
||
- [x] WebSocket 日志流
|
||
- [x] REST API 端点
|
||
- [x] API 文档 (/docs)
|
||
|
||
### 待完善 / To Be Completed 🚧
|
||
|
||
- [ ] 完整的配置编辑器
|
||
- [ ] 任务调度可视化
|
||
- [ ] 日志过滤和搜索
|
||
- [ ] 更新系统界面
|
||
- [ ] 远程访问管理界面
|
||
- [ ] 移动端响应式优化
|
||
|
||
## 开发指南 / Development Guide
|
||
|
||
### 添加新的 API 端点 / Adding New API Endpoints
|
||
|
||
1. 在 `module/webui/fastapi_backend/routes/` 中创建或修改文件
|
||
2. 定义 Pydantic 模型用于请求/响应验证
|
||
3. 在 `main.py` 中注册路由器
|
||
|
||
示例 / Example:
|
||
|
||
```python
|
||
# routes/my_feature.py
|
||
from fastapi import APIRouter
|
||
from pydantic import BaseModel
|
||
|
||
router = APIRouter()
|
||
|
||
class MyRequest(BaseModel):
|
||
value: str
|
||
|
||
@router.post("/my-endpoint")
|
||
async def my_endpoint(request: MyRequest):
|
||
return {"status": "success", "received": request.value}
|
||
|
||
# main.py
|
||
from module.webui.fastapi_backend.routes import my_feature
|
||
app.include_router(my_feature.router, prefix="/api/my-feature", tags=["my-feature"])
|
||
```
|
||
|
||
### 修改前端 / Modifying Frontend
|
||
|
||
主要的前端文件：
|
||
|
||
Main frontend file:
|
||
|
||
- `module/webui/fastapi_backend/templates/index.html`
|
||
|
||
可以添加新的模板文件或静态资源到：
|
||
|
||
You can add new templates or static assets to:
|
||
|
||
- `module/webui/fastapi_backend/templates/`
|
||
- `module/webui/fastapi_backend/static/`
|
||
|
||
## 迁移建议 / Migration Recommendations
|
||
|
||
### 对于最终用户 / For End Users
|
||
|
||
1. **渐进式迁移** / **Gradual Migration**
|
||
- 继续使用 `python gui.py` 运行原有界面
|
||
- 尝试 `python gui_fastapi.py` 体验新界面
|
||
- 当新界面功能完善后再切换
|
||
|
||
2. **配置兼容** / **Config Compatibility**
|
||
- 两个界面共享相同的配置文件
|
||
- 切换界面不会丢失配置
|
||
|
||
### 对于开发者 / For Developers
|
||
|
||
1. **API 优先** / **API First**
|
||
- 使用 REST API 开发新功能
|
||
- 可以为移动端、CLI 等创建新客户端
|
||
|
||
2. **逐步迁移功能** / **Gradual Feature Migration**
|
||
- 从简单功能开始迁移
|
||
- 每个功能独立测试
|
||
- 保持与原有功能的兼容
|
||
|
||
## 故障排除 / Troubleshooting
|
||
|
||
### 常见问题 / Common Issues
|
||
|
||
1. **端口被占用** / **Port Already in Use**
|
||
```bash
|
||
python gui_fastapi.py --port 23468
|
||
```
|
||
|
||
2. **依赖缺失** / **Missing Dependencies**
|
||
```bash
|
||
pip install fastapi>=0.100.0 starlette>=0.27.0 uvicorn>=0.20.0 jinja2>=3.0.0
|
||
```
|
||
|
||
3. **WebSocket 连接失败** / **WebSocket Connection Failed**
|
||
- 检查防火墙设置
|
||
- 确保使用正确的协议 (ws:// 或 wss://)
|
||
|
||
4. **样式显示异常** / **Styling Issues**
|
||
- 清除浏览器缓存
|
||
- 检查 CSS 文件路径是否正确
|
||
|
||
## 技术栈 / Technology Stack
|
||
|
||
### 后端 / Backend
|
||
- FastAPI >= 0.100.0
|
||
- Starlette >= 0.27.0
|
||
- Uvicorn >= 0.20.0
|
||
- Pydantic
|
||
- Python 3.10+
|
||
|
||
### 前端 / Frontend
|
||
- HTML5
|
||
- CSS3 (Bootstrap 5)
|
||
- Vanilla JavaScript
|
||
- WebSocket API
|
||
|
||
## 性能对比 / Performance Comparison
|
||
|
||
| 指标 / Metric | PyWebIO | FastAPI |
|
||
|--------------|---------|---------|
|
||
| 启动时间 / Startup | ~2s | ~1s |
|
||
| API 响应 / API Response | N/A | <50ms |
|
||
| 内存占用 / Memory | ~100MB | ~80MB |
|
||
| 并发支持 / Concurrency | 有限 | 优秀 |
|
||
|
||
## 贡献 / Contributing
|
||
|
||
欢迎贡献代码！以下是一些可以改进的方向：
|
||
|
||
Contributions are welcome! Here are some areas for improvement:
|
||
|
||
1. 完善配置编辑器 / Complete config editor
|
||
2. 增强日志查看器 / Enhanced log viewer
|
||
3. 移动端适配 / Mobile responsiveness
|
||
4. 国际化改进 / i18n improvements
|
||
5. 单元测试 / Unit tests
|
||
6. 文档完善 / Documentation
|
||
|
||
## 反馈 / Feedback
|
||
|
||
如果遇到问题或有建议，请：
|
||
|
||
If you encounter issues or have suggestions:
|
||
|
||
1. 在 GitHub 上创建 Issue
|
||
2. 提供详细的错误信息和日志
|
||
3. 说明使用的 Python 版本和操作系统
|
||
|
||
## 许可 / License
|
||
|
||
本项目遵循与主项目相同的许可协议。
|
||
|
||
This follows the same license as the main project.
|