photography/docs/USER_MANUAL.md

# Photography Portfolio 用户使用手册

> 版本: v1.0.0  
> 更新日期: 2025-07-11  
> 适用范围: 管理员和最终用户

## 📋 目录

1. [系统概述](#系统概述)
2. [快速开始](#快速开始)
3. [管理后台使用指南](#管理后台使用指南)
4. [前端网站使用指南](#前端网站使用指南)
5. [部署运维指南](#部署运维指南)
6. [常见问题解答](#常见问题解答)
7. [故障排查](#故障排查)
8. [联系支持](#联系支持)

---

## 🎯 系统概述

Photography Portfolio 是一个现代化的摄影作品集管理系统，包含以下核心功能：

### 主要特性
- 🔐 **安全认证系统**: JWT认证，多级权限控制
- 📸 **照片管理**: 上传、编辑、分类、标签管理
- 🎨 **响应式设计**: 支持桌面端和移动端
- 🌙 **主题切换**: 深色/浅色模式
- 📊 **统计分析**: 完整的数据统计和分析功能

### 系统架构
```
前端展示网站 (photography.iriver.top)
    ↓
管理后台 (admin.photography.iriver.top)
    ↓
后端API (api.photography.iriver.top)
    ↓
数据库 (PostgreSQL)
```

---

## 🚀 快速开始

### 系统要求
- **浏览器**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- **分辨率**: 最低 1024x768 (推荐 1920x1080)
- **网络**: 宽带连接 (上传照片需要)

### 访问地址
- **前端网站**: https://photography.iriver.top
- **管理后台**: https://admin.photography.iriver.top
- **API文档**: https://api.photography.iriver.top/docs

### 默认账户
```
管理员账户:
用户名: admin
密码: admin123
邮箱: admin@photography.com

演示账户:
用户名: demo
密码: demo123
邮箱: demo@photography.com
```

---

## 🎛️ 管理后台使用指南

### 登录系统

1. 访问 https://admin.photography.iriver.top
2. 输入用户名和密码
3. 点击"登录"按钮
4. 登录成功后自动跳转到仪表板

### 仪表板概览

仪表板显示系统的核心统计信息：
- 📸 **照片总数**: 系统中的照片总量
- 📁 **分类数量**: 当前分类总数
- 🏷️ **标签数量**: 系统标签总数
- 👥 **用户数量**: 注册用户总数
- 📊 **月度统计**: 近期上传趋势

### 照片管理

#### 上传照片
1. 点击左侧菜单"照片管理"
2. 点击"上传照片"按钮
3. 选择上传方式：
   - **拖拽上传**: 直接将图片拖拽到指定区域
   - **点击上传**: 点击选择文件按钮
4. 填写照片信息：
   - 标题 (必填)
   - 描述 (可选)
   - 分类 (必填)
   - 标签 (可选，多选)
5. 点击"开始上传"
6. 等待上传完成

**支持的文件格式**: JPG, PNG, GIF, WebP  
**文件大小限制**: 单张照片最大 10MB  
**批量上传**: 最多同时上传 20 张照片

#### 管理照片
1. 在照片列表中查看所有照片
2. 使用搜索框查找特定照片
3. 切换视图模式：
   - 🔲 **网格视图**: 缩略图展示
   - 📋 **列表视图**: 详细信息展示
4. 照片操作：
   - **查看**: 点击照片查看详情
   - **编辑**: 点击操作菜单选择编辑
   - **删除**: 点击操作菜单选择删除

#### 批量操作
1. 选择多张照片 (勾选复选框)
2. 点击"批量操作"按钮
3. 选择操作类型：
   - **批量删除**: 删除选中的照片
   - **批量更新状态**: 更改照片状态
   - **批量分类**: 更改照片分类

#### 照片编辑
1. 在照片操作菜单中选择"编辑"
2. 修改照片信息：
   - 标题
   - 描述
   - 分类
   - 标签
   - 状态 (已发布/草稿)
3. 点击"保存"确认修改

### 分类管理

#### 创建分类
1. 点击左侧菜单"分类管理"
2. 点击"创建分类"按钮
3. 填写分类信息：
   - 分类名称 (必填)
   - 分类描述 (可选)
   - 父级分类 (可选，用于创建子分类)
4. 点击"创建"保存

#### 管理分类
- **树形结构**: 分类以树形结构展示层级关系
- **展开/收起**: 点击箭头图标展开或收起子分类
- **编辑分类**: 点击操作菜单选择编辑
- **删除分类**: 点击操作菜单选择删除 (注意：删除分类前需要先移除该分类下的照片)

#### 分类统计
- 每个分类显示包含的照片数量
- 分类状态指示器 (启用/禁用)
- 最后更新时间

### 用户管理

#### 查看用户
1. 点击左侧菜单"用户管理"
2. 查看用户列表和详细信息
3. 使用搜索功能查找特定用户

#### 用户操作
- **查看详情**: 点击用户名查看详细信息
- **编辑用户**: 修改用户信息和权限
- **启用/禁用**: 控制用户账户状态
- **重置密码**: 为用户重置密码

### 系统设置

#### 个人设置
1. 点击右上角用户头像
2. 选择"个人设置"
3. 修改个人信息：
   - 头像上传
   - 昵称修改
   - 邮箱更新
   - 密码修改

#### 主题设置
- 点击右上角的主题切换按钮
- 选择浅色模式或深色模式
- 设置会自动保存

---

## 🌐 前端网站使用指南

### 浏览照片

#### 主页浏览
1. 访问 https://photography.iriver.top
2. 首页展示最新上传的照片
3. 滚动查看更多照片
4. 点击照片查看大图

#### 搜索功能
1. 使用顶部搜索栏
2. 输入关键词搜索照片
3. 支持搜索：
   - 照片标题
   - 照片描述
   - 分类名称
   - 标签名称

#### 过滤功能
1. 点击"过滤"按钮
2. 选择过滤条件：
   - **分类**: 选择特定分类
   - **标签**: 选择一个或多个标签
   - **排序**: 选择排序方式
3. 点击"应用过滤"

#### 视图模式
- **网格视图**: 照片以网格形式展示
- **瀑布流**: 照片以瀑布流形式展示
- **列表视图**: 照片以列表形式展示

### 照片查看

#### 全屏查看
1. 点击任意照片打开全屏模式
2. 使用键盘控制：
   - **左右箭头**: 切换照片
   - **ESC**: 退出全屏
   - **空格**: 暂停/继续幻灯片
3. 移动端支持手势操作：
   - **左右滑动**: 切换照片
   - **双击**: 缩放照片
   - **捏合**: 缩放控制

#### 照片信息
- 照片标题和描述
- 拍摄日期和上传时间
- 分类和标签信息
- 照片统计信息

### 分类浏览

#### 分类页面
1. 点击导航栏"分类"
2. 查看所有分类列表
3. 点击分类名称查看该分类下的照片
4. 查看分类统计信息

#### 标签云
1. 点击导航栏"标签"
2. 查看标签云展示
3. 标签大小表示使用频率
4. 点击标签查看相关照片

### 移动端使用

#### 触摸操作
- **单击**: 选择照片
- **双击**: 全屏查看
- **左右滑动**: 切换照片
- **上下滑动**: 浏览列表
- **捏合**: 缩放照片

#### 响应式设计
- 自动适配不同屏幕尺寸
- 优化的移动端界面
- 触摸友好的按钮设计

---

## 🚀 部署运维指南

### 环境要求

#### 服务器配置
- **操作系统**: Ubuntu 20.04+ / CentOS 8+
- **CPU**: 2核心以上
- **内存**: 4GB以上
- **存储**: 50GB以上
- **网络**: 公网IP，备案域名

#### 软件依赖
- **Docker**: 20.10+
- **Docker Compose**: 2.0+
- **Nginx**: 1.18+ (或使用Caddy)
- **PostgreSQL**: 13+
- **Redis**: 6.0+

### 部署步骤

#### 1. 服务器准备
```bash
# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```

#### 2. 项目部署
```bash
# 克隆项目
git clone https://git.iriver.top/iriver/photography.git
cd photography

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件配置数据库等信息

# 启动服务
docker-compose up -d
```

#### 3. 数据库初始化
```bash
# 执行数据库迁移
docker-compose exec backend ./migrate up

# 导入种子数据
docker-compose exec backend ./scripts/seed_data.sh
```

#### 4. 域名配置
```bash
# 配置Caddy反向代理
sudo cp docs/deployment/Caddyfile /etc/caddy/
sudo systemctl reload caddy
```

### 监控和维护

#### 日志查看
```bash
# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f frontend
```

#### 性能监控
```bash
# 查看资源使用情况
docker stats

# 查看磁盘使用情况
df -h

# 查看数据库状态
docker-compose exec db psql -U postgres -d photography -c "SELECT * FROM pg_stat_activity;"
```

#### 备份策略
```bash
# 数据库备份
docker-compose exec db pg_dump -U postgres photography > backup_$(date +%Y%m%d).sql

# 文件备份
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz uploads/
```

### 更新部署

#### 应用程序更新
```bash
# 拉取最新代码
git pull origin main

# 重新构建镜像
docker-compose build

# 重启服务
docker-compose down
docker-compose up -d
```

#### 数据库迁移
```bash
# 执行新的迁移
docker-compose exec backend ./migrate up
```

---

## ❓ 常见问题解答

### 登录相关

**Q: 忘记密码怎么办？**
A: 请联系管理员重置密码，或使用密码找回功能。

**Q: 登录时提示"用户名或密码错误"？**
A: 请检查用户名和密码是否正确，注意大小写。如果多次失败，账户可能被锁定。

**Q: 登录后自动退出？**
A: 可能是会话过期，请重新登录。如果频繁出现，请联系管理员。

### 照片上传

**Q: 支持哪些图片格式？**
A: 支持 JPG, PNG, GIF, WebP 格式，推荐使用 JPG 格式。

**Q: 照片上传失败怎么办？**
A: 请检查：
1. 文件格式是否支持
2. 文件大小是否超过限制 (10MB)
3. 网络连接是否稳定
4. 浏览器是否支持

**Q: 批量上传照片时部分失败？**
A: 系统会显示失败的照片列表，您可以单独重新上传失败的照片。

### 性能相关

**Q: 照片加载很慢？**
A: 可能的原因：
1. 网络连接较慢
2. 照片文件过大
3. 服务器负载较高
建议: 使用压缩后的照片，优化网络环境。

**Q: 网站打开缓慢？**
A: 请检查网络连接，清除浏览器缓存，或稍后再试。

### 功能使用

**Q: 如何创建照片分类？**
A: 在管理后台的"分类管理"中点击"创建分类"按钮。

**Q: 如何批量管理照片？**
A: 在照片列表中勾选多张照片，然后使用"批量操作"功能。

**Q: 如何搜索照片？**
A: 使用搜索框输入关键词，支持搜索标题、描述、分类和标签。

---

## 🔧 故障排查

### 常见错误

#### 1. 500 服务器内部错误
**症状**: 访问网站时显示"500 Internal Server Error"
**排查步骤**:
1. 检查服务器日志: `sudo tail -f /var/log/photography/error.log`
2. 检查数据库连接: `docker-compose exec backend ./health-check`
3. 检查磁盘空间: `df -h`
4. 重启服务: `docker-compose restart`

#### 2. 无法连接数据库
**症状**: 登录失败，提示数据库连接错误
**排查步骤**:
1. 检查数据库服务状态: `docker-compose ps`
2. 检查数据库日志: `docker-compose logs db`
3. 验证数据库配置: 检查 `.env` 文件中的数据库配置
4. 重启数据库: `docker-compose restart db`

#### 3. 照片上传失败
**症状**: 上传照片时提示失败或超时
**排查步骤**:
1. 检查上传目录权限: `ls -la uploads/`
2. 检查磁盘空间: `df -h`
3. 检查文件大小限制: 确认文件不超过10MB
4. 检查网络连接: 确认网络稳定

#### 4. 静态资源无法访问
**症状**: 照片或样式文件无法加载
**排查步骤**:
1. 检查Nginx/Caddy配置: `sudo nginx -t` 或 `caddy validate`
2. 检查文件权限: `ls -la /var/www/photography/`
3. 检查防火墙设置: `sudo ufw status`
4. 重启Web服务器: `sudo systemctl restart nginx`

### 性能优化

#### 1. 数据库优化
```sql
-- 检查数据库性能
SELECT * FROM pg_stat_activity WHERE state = 'active';

-- 重建索引
REINDEX DATABASE photography;

-- 更新统计信息
ANALYZE;
```

#### 2. 缓存优化
```bash
# 清除Redis缓存
docker-compose exec redis redis-cli FLUSHALL

# 重启Redis
docker-compose restart redis
```

#### 3. 磁盘清理
```bash
# 清理Docker无用镜像
docker system prune -a

# 清理旧的日志文件
sudo find /var/log -name "*.log" -mtime +30 -delete

# 清理上传的临时文件
find uploads/tmp -name "*" -mtime +1 -delete
```

### 监控命令

#### 系统监控
```bash
# 查看系统负载
htop

# 查看内存使用
free -h

# 查看磁盘IO
iostat -x 1

# 查看网络连接
netstat -tuln
```

#### 应用监控
```bash
# 查看API响应时间
curl -w "@curl-format.txt" -o /dev/null -s "https://api.photography.iriver.top/health"

# 查看数据库连接数
docker-compose exec db psql -U postgres -d photography -c "SELECT count(*) FROM pg_stat_activity;"

# 查看服务状态
docker-compose ps
```

---

## 📞 联系支持

### 技术支持
- **邮箱**: support@photography.iriver.top
- **QQ群**: 123456789
- **工作时间**: 周一至周五 9:00-18:00

### 问题反馈
- **GitHub Issues**: https://github.com/iriver/photography/issues
- **在线文档**: https://docs.photography.iriver.top
- **更新日志**: https://changelog.photography.iriver.top

### 紧急联系
- **运维热线**: 400-XXX-XXXX
- **紧急邮箱**: urgent@photography.iriver.top

---

## 📝 更新日志

### v1.0.0 (2025-07-11)
- 📖 创建完整的用户使用手册
- 🎛️ 详细的管理后台使用指南
- 🌐 前端网站使用说明
- 🚀 部署运维完整指南
- 🔧 故障排查和性能优化指南
- 📞 完善的技术支持体系

---

*本文档将根据系统更新持续完善，请定期查看最新版本。*