Simple Server 开发文档与架构解析
Simple Server 是一个轻量级 PHP RESTful API 服务框架，为 DOO 应用提供后端支撑。本文为 Simple Server 独立开发文档与架构解析。
## 一、框架定位
Simple Server 是**中间件链 + 服务-仓库分层**的轻量级 API 框架，零第三方框架依赖（纯 PHP 7.2+ 实现），单入口路由 + 90+ 接口文件，内置频率限制、RBAC 权限、考勤薪资计算、自动化爬虫等业务模块，配套统一管理后台 API。
核心设计目标：
- **轻量**：无 Composer 运行时依赖，PHP + MySQL 即可部署
- **统一入口**：所有请求经 `.htaccess` 进入 `index.php` 集中分发
- **分层清晰**：中间件 → 路由 → 服务 → 仓库 → 数据库
- **安全默认**：PDO 预处理、bcrypt、频率限制、Session/Token 双认证
## 二、请求生命周期
```
HTTP Request
│
▼
┌──────────────────────┐
│ .htaccess Rewrite │ /api/* → index.php?__route=...
└──────────┬───────────┘
▼
┌──────────────────────┐
│ CORS 中间件 │ 白名单 + OPTIONS 预检
└──────────┬───────────┘
▼
┌──────────────────────┐
│ 日志中间件 │ JSON 请求/响应日志 + 耗时
└──────────┬───────────┘
▼
┌──────────────────────┐
│ 错误中间件 │ 全局异常捕获 + 脱敏
└──────────┬───────────┘
▼
┌──────────────────────┐
│ 路由分发 index.php │ 86+ 路由（RESTful + 文件路由）
└──────────┬───────────┘
▼
┌──────────────────────┐
│ Service 层 │ 业务逻辑 / 权限 / 编排
└──────────┬───────────┘
▼
┌──────────────────────┐
│ Repository 层 │ SQL 构建 / PDO 执行
└──────────┬───────────┘
▼
MySQL 数据库
```
## 三、核心组件
### 1. 统一路由入口（index.php · 428 行 · 86+ 路由）
所有 `/api/*` 请求经 `.htaccess` rewrite 进入 `index.php`，按 `__route` 参数分发：
| 路由类型 | 示例 | 处理方式 |
|----------|------|----------|
| RESTful 核心路由 | `auth/login`、`users/1`、`content` | 直接调用 Service 层 |
| 传统文件路由 | `login`、`feedback`、`overtime` | `require` 对应 API 文件 |
| 管理路由 | `admin_*` 系列（15 个） | 校验管理员会话后分发 |
```apache
# .htaccess
RewriteRule ^api/(.*)$ api/index.php?__route=$1 [QSA,L]
```
### 2. 中间件链（middleware/）
| 中间件 | 职责 |
|--------|------|
| CorsMiddleware | 跨域白名单（.env 配置）+ OPTIONS 预检响应 |
| LogMiddleware | 请求/响应 JSON 日志 + 毫秒级耗时统计 |
| ErrorMiddleware | try/catch 全局异常捕获，生产环境错误脱敏 |
| AuthMiddleware | Session/Token 认证，按需在路由中调用 |
中间件采用链式调用：每个中间件持有 `$next` 引用，`handle()` 中处理完自身逻辑后调用 `$next->handle()`。
### 3. 配置管理（config/）
| 文件 | 职责 |
|------|------|
| Config.php | `.env` 配置读取（DB、SMTP、CORS、API 密钥） |
| Database.php | PDO 连接封装（utf8mb4 + 预处理默认开启） |
| RateLimiter.php | 基于数据库的 IP+操作 频率限制 |
`.env` 配置项：DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASS、CORS_ORIGIN、SMTP_*、API_SECRET、API_DEBUG。
### 4. 服务-仓库分层（services/ + repositories/）
```
UserService / ContentService ← 业务逻辑、权限验证、流程编排
↓
UserRepository / ContentRepository ← SQL 构建、PDO 执行（全量预处理）
↓
MySQL
```
Service 层与 Repository 层解耦：控制器不直接写 SQL，业务变化只改 Service，数据访问只改 Repository。
## 四、API 模块总览（90+ 接口）
### 认证与用户
| 接口 | 说明 |
|------|------|
| login / register | 登录注册（频率限制 5次/5分、3次/10分） |
| forgot_password / reset_password | 邮件验证码找回密码 |
| change_password / delete_account | 修改密码 / 注销账号 |
| get_users / update_user / user_level | 用户列表 / 资料更新 / 等级积分 |
### 内容与文章
| 接口 | 说明 |
|------|------|
| content (CRUD) | 统一内容表管理（图文/视频/文章） |
| feed / get_carousels | 信息流 / 轮播图 |
| get_articles / upload_article / delete_article | 文章系统（分类筛选） |
| add_collection / get_collections | 收藏管理 |
| announcements | 公告列表 |
### 考勤与薪资
| 接口 | 说明 |
|------|------|
| overtime | 加班/调休记录 + 薪资总览 |
| salary_config | 五险一金费率 + 个税（累计预扣法）计算 |
### 反馈闭环
feedback（提交/查询）→ admin_feedback（管理员处理）→ feedback_answer（回复）→ 用户端查看，状态流转：0 待处理 → 1 已查看 → 2 已回复。
### 文件与上传
upload / upload_image / files / files_preview / files_upload / download_proxy（APK 下载代理，防路径穿越）。
### 管理后台（15 个 admin_* 接口，均需管理员会话/Token）
admin_users · admin_content · admin_carousels · admin_follows · admin_messages · admin_stats · admin_logs · admin_articles · admin_feedback · admin_permissions · admin_overtime · admin_apis · admin_login · admin_logout
### 爬虫与自动化
| 接口 | 数据源 |
|------|--------|
| crawl_hotsearch | 通用热榜 |
| crawl_douyin_hotsearch | 抖音热榜 |
| crawl_toutiao_hotsearch | 今日头条热榜 |
| crawl_images | 随机图片抓取 |
### 系统与运维
system_monitor（服务器/数据库/API 耗时）、deploy（Token 验证部署）、check_update / get_versions / upload_version / wgt_manager（版本与热更新管理）、ai_proxy（AI 代理转发）。
## 五、数据库设计（27 张表）
| 分类 | 表 |
|------|-----|
| 用户 | users（含 level/experience/points 等级积分） |
| 内容 | content、articles、carousels、collections、images、files |
| 社交 | follows |
| 考勤薪资 | attendance、overtime、overtime_config、salary_config |
| 反馈 | feedback、feedback_replies |
| 权限 | roles、permissions、role_permissions、user_roles |
| 系统 | logs、rate_limits、user_behaviors、email_verifications、password_resets、splash_config、app_versions、env_monitor、announcements |
所有表 InnoDB + utf8mb4，外键关联 user_id，时间戳自动维护。
## 六、RBAC 权限系统
4 个默认角色（super_admin → admin → editor → user），12 项权限（manage_users、manage_content、manage_messages 等），通过 role_permissions / user_roles 关联，可动态创建角色并分配权限。`setup_admin_role.php` 一键初始化。
## 七、安全机制
| 措施 | 实现 |
|------|------|
| 密码加密 | password_hash / password_verify（bcrypt） |
| SQL 注入防护 | 全量 PDO prepare + bind |
| 频率限制 | RateLimiter（login 5次/5分，register 3次/10分） |
| 管理员认证 | admin_* 统一会话校验 + Token 支持 |
| 错误脱敏 | ErrorMiddleware 按 API_DEBUG 开关 |
| CORS 白名单 | .env 配置，非白名单源拒绝 |
| 路径穿越防护 | download_proxy 使用 basename() |
## 八、部署
- **环境**：PHP 7.2+ / MySQL 5.7+ / Nginx 或 Apache（mod_rewrite）
- **目录**：`server/`（api、config、middleware、services、repositories、sql、uploads、downloads）
- **初始化**：`init_database.php` 建表 → `reset_admin.php` 重置管理员 → `setup_admin_role.php` 初始化角色
- **线上实例**：Ubuntu 22.04 + Nginx :7070，数据库 doo-app（27 表），PM2 守护
## 九、版本历程
| 版本 | 日期 | 关键内容 |
|------|------|----------|
| v2.4.0 | 2026-07-18 | 反馈闭环、admin-vue 重构、Token 鉴权 |
| v2.3.0 | 2026-06-21 | api-bridge 修复 401、反馈管理完善 |
| v2.2.0 | 2026-06-20 | 统一路由入口（86+ 路由） |
| v2.1.0 | 2026-06-20 | 分页修复、错误脱敏、CORS 覆盖 |
| v2.0.0 | 2026-06-20 | 更名 Simple Server，考勤/RBAC/爬虫 |
---
**项目地址**：https://github.com/jackchenjiufu/Simple