Simple Server 开发文档与架构解析

Simple Server 是一个轻量级 PHP RESTful API 服务框架，为 DOO 应用提供后端支撑。本文为 Simple Server 独立开发文档与架构解析。

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 个）	校验管理员会话后分发

# .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 张表）

Simple Server 数据库

分类	表
用户	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

📝 本文由AI生成