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. 服务器准备

# 更新系统
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. 项目部署

# 克隆项目
git clone https://git.iriver.top/iriver/photography.git
cd photography

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

# 启动服务
docker-compose up -d

3. 数据库初始化

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

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

4. 域名配置

# 配置Caddy反向代理
sudo cp docs/deployment/Caddyfile /etc/caddy/
sudo systemctl reload caddy

监控和维护

日志查看

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

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

性能监控

# 查看资源使用情况
docker stats

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

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

备份策略

# 数据库备份
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/

更新部署

应用程序更新

# 拉取最新代码
git pull origin main

# 重新构建镜像
docker-compose build

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

数据库迁移

# 执行新的迁移
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. 数据库优化

-- 检查数据库性能
SELECT * FROM pg_stat_activity WHERE state = 'active';

-- 重建索引
REINDEX DATABASE photography;

-- 更新统计信息
ANALYZE;

2. 缓存优化

# 清除Redis缓存
docker-compose exec redis redis-cli FLUSHALL

# 重启Redis
docker-compose restart redis

3. 磁盘清理

# 清理Docker无用镜像
docker system prune -a

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

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

监控命令

系统监控

# 查看系统负载
htop

# 查看内存使用
free -h

# 查看磁盘IO
iostat -x 1

# 查看网络连接
netstat -tuln

应用监控

# 查看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)

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

---

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