# 逍遥图库系统

**Repository Path**: sinma/zeaya

## Basic Information

- **Project Name**: 逍遥图库系统
- **Description**: 逍遥图库系统 Carefree Photo Gallery - Zeaya
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://www.sinma.net
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-12
- **Last Updated**: 2026-02-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zeaya - 逍遥图库系统 - 现代化图片社区系统

[![CI Status](https://img.shields.io/badge/CI-passing-brightgreen)]()
[![Code Quality](https://img.shields.io/badge/PHPStan-Level%206-blue)]()
[![PHP Version](https://img.shields.io/badge/PHP-8.0%2B-777BB4)]()
[![License](https://img.shields.io/badge/license-Apache--2.0-green)]()
[![Version](https://img.shields.io/badge/version-1.1.0-orange)]()

逍遥图库系统 Zeaya 是一款基于 ThinkPHP 8 + MySQL 8 开发的企业级现代化图库管理系统。 系统采用前后端分离架构，后端使用 PHP 8 + ThinkPHP 8 框架，前端使用 Vue 3 构建响应式界面。

Zeaya 提供完善的图片管理功能，包括多级相册分类、智能相册自动归类、标签系统、图片编辑与滤镜、 评论互动、点赞收藏、分享功能等。系统支持瀑布流、网格、拼图等多种布局模式， 采用渐进式图片加载和懒加载技术，确保流畅的用户体验。

系统内置完整的 RBAC 权限管理、内容审核机制、API 限流保护、CSRF/XSS 防护等安全特性， 支持 PWA 离线访问、Service Worker 缓存、暗色/亮色主题切换，是个人或企业搭建图库平台的理想选择。

[Demo](https://zeaya.carefreecode.com/)

[使用说明手册](https://zeaya-docs.carefreecode.com/)

## ✨ 核心特性

### 🔒 安全性 (P0完成 100%)
- ✅ XSS/SQL注入/CSRF全面防护（可配置开关）
- ✅ 文件上传安全验证与路径遍历防护
- ✅ Policy权限控制系统
- ✅ 会话安全加固（HttpOnly、Secure Cookie）
- ✅ 敏感信息保护与日志脱敏
- ✅ 细粒度API限流配置

### ⚡ 性能优化 (P0-P1完成 100%)
- ✅ Redis缓存系统（查询缓存、标签管理）
- ✅ 数据库索引优化（复合索引、高频查询优化）
- ✅ API智能限流（令牌桶算法）
- ✅ 图片异步处理队列
- ✅ OPcache生产环境加速

### 🏗️ 架构设计 (P2完成 100%)
- ✅ Repository模式 - 数据访问层抽象
- ✅ Service层 - 业务逻辑分离
- ✅ 控制器重构 - 单一职责原则
- ✅ 标准化错误码系统（70+业务错误码）
- ✅ 统一API响应格式

### ⚙️ 系统设置 (v1.1.0 新增)
- ✅ 数据库驱动的配置管理系统
- ✅ 5大配置分组（系统/上传/安全/性能/功能）
- ✅ 可视化管理界面
- ✅ 图片类型配置支持上传
- ✅ 完整SEO优化支持（Meta/OG/Twitter Card）

### 📊 监控与文档 (P2-P3完成)
- ✅ 健康检查接口（/health、/health/live、/health/ready）
- ✅ OpenAPI 3.0规范 + Swagger UI
- ✅ 完整技术文档（架构、部署、CI/CD）
- ✅ 多通道日志系统（操作、安全、系统、SQL）

### 🧪 代码质量 (P3完成 100%)
- ✅ PHPUnit单元测试框架
- ✅ API集成测试套件 (58个测试用例)
- ✅ PHPStan Level 6静态分析
- ✅ PSR-12代码规范
- ✅ APM性能监控集成

### 🐳 DevOps (P4完成 100%)
- ✅ Docker完整容器化部署
- ✅ GitHub Actions CI/CD流水线
- ✅ Prometheus + Grafana监控系统
- ✅ ELK Stack日志收集与分析
- ✅ 自动化备份与恢复策略
- ✅ 自动化测试与部署

## 📊 项目完成度

**总体进度: 100% (31/31核心任务) 🎉**

| 优先级 | 进度 | 任务数 |
|--------|------|--------|
| P0 - 核心安全与性能 | ✅ 100% | 10/10 |
| P1 - 核心功能优化 | ✅ 100% | 5/5 |
| P2 - 架构改进 | ✅ 100% | 5/5 |
| P3 - 代码质量与测试 | ✅ 100% | 6/6 |
| P4 - 运维与部署 | ✅ 100% | 5/5 |
| P5 - 高级特性 | ⏳ 0% | 0/5 |


## 🚀 快速开始

### 使用Docker（推荐）

```bash
# 1. 克隆项目
git clone https://gitee.com/sinma/zeaya.git photo-gallery
cd photo-gallery

# 2. 配置环境
cp .env.docker .env

# 3. 启动服务
docker-compose up -d

# 4. 访问应用
# - 主页: http://localhost:8000
# - API文档: http://localhost:8000/api-docs
# - 健康检查: http://localhost:8000/health
# - phpMyAdmin: http://localhost:8080 (开发环境)
```

详细说明: [Docker部署文档](docs/DOCKER_DEPLOYMENT.md)

### 传统部署

```bash
composer install
cp .env.example .env
# 编辑 .env 配置
php think migrate:run
php think run
```

## 📁 项目结构

```
photo-gallery/
├── app/
│   ├── controller/         # 控制器（拆分为多个专注模块）
│   ├── service/           # Service层（业务逻辑）
│   ├── repository/        # Repository层（数据访问）
│   ├── model/             # Model层（ORM）
│   ├── validate/          # 验证器（多场景）
│   ├── policy/            # Policy权限策略
│   ├── constant/          # 常量（ErrorCode等）
│   └── traits/            # Traits（ApiResponse等）
├── docker/                # Docker配置
├── docs/                  # 完整文档
├── tests/                 # 测试（Unit + Feature）
├── .github/workflows/     # CI/CD配置
└── [配置文件]
```

## 📚 文档导航

### 必读文档
- [📖 系统架构文档](docs/ARCHITECTURE.md) - 完整技术架构
- [🐳 Docker部署文档](docs/DOCKER_DEPLOYMENT.md) - 容器化部署
- [🔄 CI/CD文档](docs/CI_CD.md) - 自动化流程
- [📊 监控告警文档](docs/MONITORING.md) - Prometheus + Grafana
- [⚡ APM性能监控文档](docs/APM.md) - 应用性能监控系统
- [📝 日志分析文档](docs/LOGGING.md) - ELK Stack日志系统
- [💾 备份恢复文档](docs/BACKUP.md) - 自动化备份与灾难恢复
- [✅ 代码质量文档](docs/CODE_QUALITY.md) - 质量保障
- [🔢 错误码规范](docs/ERROR_CODES.md) - 标准错误码

### 开发文档
- [🧪 测试文档](tests/README.md) - 测试指南
- [📝 任务清单](todo.md) - 开发进度

## 🛠️ 技术栈

- **框架**: ThinkPHP 8.x
- **PHP**: 8.0+
- **数据库**: MySQL 8.0
- **缓存**: Redis 7
- **测试**: PHPUnit 10.x
- **静态分析**: PHPStan Level 6
- **容器**: Docker & Docker Compose
- **CI/CD**: GitHub Actions

## 🔧 开发命令

### 测试
```bash
vendor/bin/phpunit                    # 所有测试
vendor/bin/phpunit --testsuite=Unit   # 单元测试
vendor/bin/phpunit --coverage-html coverage/  # 覆盖率报告
```

### 代码质量
```bash
vendor/bin/phpstan analyse            # 静态分析
vendor/bin/phpcs app --standard=PSR12 # 代码风格检查
```

### Docker操作
```bash
docker-compose up -d                  # 启动服务
docker-compose logs -f app            # 查看日志
docker-compose exec app bash         # 进入容器
docker-compose restart app            # 重启服务
```

## 🔐 核心安全特性

| 威胁类型 | 防护措施 | 状态 |
|---------|---------|------|
| XSS | 输出自动转义 + CSP | ✅ |
| SQL注入 | 参数绑定 + 查询构建器 | ✅ |
| CSRF | Token验证 + Same-Site Cookie | ✅ |
| 文件上传 | MIME验证 + 大小限制 + 路径检查 | ✅ |
| 未授权访问 | Policy + RBAC | ✅ |
| 会话劫持 | HttpOnly + Secure + 过期控制 | ✅ |
| 暴力破解 | API限流 + 失败计数 | ✅ |

## 🎯 核心功能

- **用户系统**: 注册/登录、权限管理、积分系统
- **图片管理**: 上传/编辑、相册管理、批量操作
- **图片编辑**: 裁剪、旋转、翻转、滤镜、水印
- **社交功能**: 点赞、收藏、评论、分享
- **管理后台**: 内容审核、用户管理、数据统计

## 🚦 API健康检查

```bash
curl http://localhost:8000/health        # 完整健康检查
curl http://localhost:8000/health/live   # 存活探测（K8s）
curl http://localhost:8000/health/ready  # 就绪探测（K8s）
curl http://localhost:8000/health/info   # 系统信息
```

## 🤝 贡献

欢迎贡献！请遵循以下规范：

1. Fork项目并创建特性分支
2. 遵循PSR-12代码规范
3. 编写单元测试
4. 通过PHPStan检查
5. 提交Pull Request

**Gitee项目地址**: [https://gitee.com/sinma/zeaya](https://gitee.com/sinma/zeaya)

**Github项目地址**: [https://github.com/carefree-code/Zeaya](https://github.com/carefree-code/Zeaya)


## 📞 联系方式

- 📧 邮箱：42033223@qq.com
- 💬 QQ：42033223
- 🌐 网站：[https://www.carefreecode.com](https://www.carefreecode.com)

## 📄 许可证

Apache-2.0 License

---

**Built with ❤️ using ThinkPHP 8**