feat: 添加产品经理和全栈开发角色资源文件

初始化产品经理和全栈开发角色的相关资源文件,包括角色定义、知识库、思维模式和执行流程文档
This commit is contained in:
2025-07-21 22:47:16 +08:00
parent 581bd40184
commit ff20f6f23a
104 changed files with 74 additions and 9967 deletions

View File

@ -0,0 +1,226 @@
# Deployment Module - CLAUDE.md
此文件为 Claude Code 在部署模块中工作时提供指导。
## 模块说明
这是摄影作品集项目的部署配置模块,包含 Web 服务器配置、权限脚本和部署文档。
## 部署架构
### 当前部署方案
- **前端**: 静态文件部署到 `/home/gitea/www/photography/`
- **Web 服务器**: Caddy (自动 HTTPS + Let's Encrypt)
- **域名**: https://photography.iriver.top
- **CI/CD**: Gitea Actions 自动部署
## 文件说明
### 配置文件
- **`Caddyfile`** - Caddy Web 服务器配置文件
- **`fix-caddy-permissions.sh`** - Caddy 权限修复脚本
### 文档
- **`caddy-setup.md`** - Caddy 服务器配置和部署指南
- **`README.md`** - 部署文档概览
## 部署流程
### 自动部署(推荐)
```bash
# 1. 推送代码触发 CI/CD
git push origin main
# CI/CD 会自动执行:
# - 安装依赖 (bun install)
# - 类型检查 (bun run type-check)
# - 代码检查 (bun run lint)
# - 构建项目 (bun run build)
# - 部署到服务器 (rsync 到 ~/www/photography/)
```
### 手动部署
```bash
# 1. 构建前端项目
cd frontend && make build
# 2. 上传静态文件
rsync -avz frontend/out/ user@server:~/www/photography/
# 3. 设置权限
ssh user@server 'chmod -R 755 ~/www/photography'
```
## Caddy 配置
### 主要功能
- **自动 HTTPS**: Let's Encrypt 证书自动获取和续期
- **静态文件服务**: 直接提供 HTML/CSS/JS/图片
- **Gzip 压缩**: 减少传输大小
- **缓存控制**: 静态资源长期缓存HTML 短期缓存
- **安全头**: XSS 保护、防点击劫持等
- **错误处理**: 404 重定向到 404.html
### 配置特点
```bash
# 域名
photography.iriver.top
# 根目录
root * /home/gitea/www/photography
# 安全和性能优化
encode gzip
header Cache-Control "public, max-age=31536000" @static
header X-Frame-Options "SAMEORIGIN"
```
## 服务器配置
### 初次配置(仅需一次)
```bash
# 1. 上传 Caddy 配置
scp docs/deployment/Caddyfile user@server:/etc/caddy/Caddyfile
# 2. 修复权限问题
scp docs/deployment/fix-caddy-permissions.sh user@server:~/
ssh user@server './fix-caddy-permissions.sh'
# 3. 重新加载 Caddy
ssh user@server 'sudo systemctl reload caddy'
# 4. 验证状态
ssh user@server 'sudo systemctl status caddy'
```
### 权限修复脚本功能
`fix-caddy-permissions.sh` 脚本会:
- 设置 `/home/gitea` 目录权限为 755
- 设置 `/home/gitea/www` 权限为 755
- 设置 `/home/gitea/www/photography` 权限为 755
- 确保 caddy 用户可以访问所有必要文件
## 故障排除
### 常见问题
#### 1. Permission denied 错误
```bash
# 检查权限
ls -la /home/gitea/www/photography
# 运行修复脚本
./fix-caddy-permissions.sh
# 验证 caddy 用户访问
sudo -u caddy ls -la /home/gitea/www/photography
```
#### 2. 404 Not Found 错误
```bash
# 检查文件是否存在
ls -la /home/gitea/www/photography/index.html
# 检查 Caddy 配置
sudo caddy validate --config /etc/caddy/Caddyfile
```
#### 3. SSL 证书问题
```bash
# 检查域名 DNS 记录
dig photography.iriver.top
# 查看 Caddy 日志
sudo journalctl -u caddy -f
```
### 日志查看
```bash
# 系统日志
sudo journalctl -u caddy -f
# Caddy 访问日志
sudo tail -f /var/log/caddy/photography.log
```
## 安全配置
### SSL/TLS
- 自动获取 Let's Encrypt 证书
- 强制 HTTPS 重定向
- HSTS 头启用max-age=31536000
### 安全头
- `X-Frame-Options: SAMEORIGIN` - 防止点击劫持
- `X-Content-Type-Options: nosniff` - 防止 MIME 嗅探
- `X-XSS-Protection: 1; mode=block` - XSS 保护
### 访问控制
- 静态文件直接服务,无需特殊权限
- 目录浏览禁用
- 隐藏服务器版本信息
## 性能优化
### 缓存策略
```bash
# 静态资源1年缓存
*.css, *.js, *.png, *.jpg, *.woff2
Cache-Control: public, max-age=31536000, immutable
# HTML 文件1小时缓存
*.html
Cache-Control: public, max-age=3600
```
### 压缩
- Gzip 压缩所有文本文件
- 自动内容编码协商
### 日志轮转
- 日志文件大小10MB 轮转
- 保留文件数5个
- JSON 格式便于分析
## 监控
### 健康检查
```bash
# 检查服务状态
sudo systemctl status caddy
# 检查端口监听
sudo netstat -tulpn | grep :443
# 测试 HTTPS 连接
curl -I https://photography.iriver.top
```
### 性能监控
- 访问日志分析
- 响应时间监控
- 错误率统计
## 备份策略
### 配置备份
- Caddyfile 版本控制Git
- 自动配置备份到 S3/对象存储
### 数据备份
- 静态文件通过 CI/CD 自动同步
- 日志文件定期归档
## 扩展计划
### 支持的部署平台
-**Caddy + Static Files** (当前)
- 📋 Vercel (计划)
- 📋 Netlify (计划)
- 📋 Docker (计划)
- 📋 Kubernetes (长期计划)
### 功能扩展
- CDN 集成
- 多区域部署
- 蓝绿部署
- 自动回滚机制

View File

@ -0,0 +1,207 @@
# Photography Portfolio Caddyfile
# 前端展示网站和后端API反向代理配置
# 前端展示网站
photography.iriver.top {
# 静态文件服务
root * /home/gitea/www/photography
# 启用文件服务器
file_server
# 启用 gzip 压缩
encode gzip
# 设置默认首页
try_files {path} {path}/ /index.html
# 设置静态资源缓存
@static {
path *.css *.js *.png *.jpg *.jpeg *.gif *.svg *.woff *.woff2 *.ttf *.eot *.ico
}
header @static Cache-Control "public, max-age=31536000, immutable"
# 设置 HTML 文件缓存
@html {
path *.html
}
header @html Cache-Control "public, max-age=3600"
# 安全头设置
header {
# 防止点击劫持
X-Frame-Options "SAMEORIGIN"
# 防止 MIME 类型嗅探
X-Content-Type-Options "nosniff"
# XSS 保护
X-XSS-Protection "1; mode=block"
# 推荐 HTTPS
Strict-Transport-Security "max-age=31536000; includeSubDomains"
# 隐藏服务器信息
-Server
}
# 日志配置
log {
output file /var/log/caddy/photography.log {
roll_size 10MB
roll_keep 5
}
format json
}
# 错误页面处理
handle_errors {
@404 {
expression {http.error.status_code} == 404
}
rewrite @404 /404.html
file_server
}
}
# 后端API反向代理
api.photography.iriver.top {
# 反向代理到后端服务
reverse_proxy localhost:8080 {
# 健康检查
health_uri /health
health_interval 30s
health_timeout 5s
health_status 200
# 故障转移
fail_duration 30s
max_fails 3
unhealthy_status 5xx
# 请求头设置
header_up Host {upstream_hostport}
header_up X-Real-IP {remote_host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
header_up X-Forwarded-Host {host}
# 响应头设置
header_down -Server
header_down Access-Control-Allow-Origin "*"
header_down Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
header_down Access-Control-Allow-Headers "Content-Type, Authorization"
}
# 启用 gzip 压缩
encode gzip
# 请求日志
log {
output file /var/log/caddy/api.photography.log {
roll_size 10MB
roll_keep 5
}
format json
}
# 限流配置
rate_limit {
zone dynamic {
key {remote_host}
events 100
window 1m
}
zone static {
key {remote_host}
events 500
window 1m
}
}
# 安全头设置
header {
# 防止点击劫持
X-Frame-Options "DENY"
# 防止 MIME 类型嗅探
X-Content-Type-Options "nosniff"
# XSS 保护
X-XSS-Protection "1; mode=block"
# 推荐 HTTPS
Strict-Transport-Security "max-age=31536000; includeSubDomains"
# 隐藏服务器信息
-Server
}
# 错误处理
handle_errors {
@5xx {
expression {http.error.status_code} >= 500
}
respond @5xx `{"error": "", "code": 500, "message": "API"}` 500 {
header Content-Type "application/json"
}
@4xx {
expression {http.error.status_code} >= 400
}
respond @4xx `{"error": "", "code": {http.error.status_code}, "message": ""}` {http.error.status_code} {
header Content-Type "application/json"
}
}
}
# 管理后台
admin.photography.iriver.top {
# 静态文件服务
root * /home/gitea/www/photography-admin
# 启用文件服务器
file_server
# 启用 gzip 压缩
encode gzip
# 设置默认首页
try_files {path} {path}/ /index.html
# 设置静态资源缓存
@static {
path *.css *.js *.png *.jpg *.jpeg *.gif *.svg *.woff *.woff2 *.ttf *.eot *.ico
}
header @static Cache-Control "public, max-age=31536000, immutable"
# 设置 HTML 文件缓存
@html {
path *.html
}
header @html Cache-Control "public, max-age=3600"
# 安全头设置
header {
# 防止点击劫持
X-Frame-Options "SAMEORIGIN"
# 防止 MIME 类型嗅探
X-Content-Type-Options "nosniff"
# XSS 保护
X-XSS-Protection "1; mode=block"
# 推荐 HTTPS
Strict-Transport-Security "max-age=31536000; includeSubDomains"
# 隐藏服务器信息
-Server
}
# 日志配置
log {
output file /var/log/caddy/admin.photography.log {
roll_size 10MB
roll_keep 5
}
format json
}
# 错误页面处理
handle_errors {
@404 {
expression {http.error.status_code} == 404
}
rewrite @404 /index.html
file_server
}
}

View File

@ -0,0 +1,58 @@
# 部署文档
本目录包含摄影作品集项目的部署相关文档。
## 目录结构
- `caddy-setup.md` - Caddy Web 服务器配置指南
- `Caddyfile` - Caddy 配置文件
- `fix-caddy-permissions.sh` - Caddy 权限修复脚本
- `environments.md` - 环境配置说明(计划中)
- `vercel-deployment.md` - Vercel 部署指南(计划中)
- `docker-deployment.md` - Docker 部署指南(计划中)
- `ci-cd.md` - CI/CD 配置说明(计划中)
- `monitoring.md` - 监控和日志配置(计划中)
- `backup.md` - 备份策略(计划中)
## 部署准备
在部署前,请确保完成以下步骤:
1. 代码检查: `make lint`
2. 类型检查: `make type-check`
3. 构建测试: `make build`
4. 完整部署准备: `make deploy-prep`
## 环境变量
确保在部署环境中配置以下环境变量:
```bash
NEXT_PUBLIC_API_URL=your-api-url
```
## 当前部署方案
### Caddy + Static Files
- **前端**: 静态文件部署到 `~/www/photography/`
- **Web 服务器**: Caddy (自动 HTTPS)
- **域名**: https://photography.iriver.top
- **CI/CD**: Gitea Actions 自动部署
### 快速部署命令
```bash
# 1. 推送代码触发自动部署
git push origin main
# 2. 配置 Web 服务器(仅首次)
scp docs/deployment/Caddyfile user@server:/etc/caddy/Caddyfile
scp docs/deployment/fix-caddy-permissions.sh user@server:~/
ssh user@server './fix-caddy-permissions.sh && sudo systemctl reload caddy'
```
## 支持的部署平台
-**Caddy + Static Files** (当前使用)
- 📋 Vercel (计划中)
- 📋 Netlify (计划中)
- 📋 Docker (计划中)

View File

@ -0,0 +1,137 @@
# Caddy 配置指南
## 配置文件位置
`Caddyfile` 复制到服务器的 Caddy 配置目录:
### 常见位置:
- Ubuntu/Debian: `/etc/caddy/Caddyfile`
- CentOS/RHEL: `/etc/caddy/Caddyfile`
- 用户目录: `~/Caddyfile`
## 部署步骤
### 1. 上传配置文件
```bash
# 将 Caddyfile 上传到服务器
scp docs/deployment/Caddyfile user@server:/etc/caddy/Caddyfile
```
### 2. 修复权限问题
```bash
# 上传权限修复脚本
scp docs/deployment/fix-caddy-permissions.sh user@server:~/
ssh user@server 'chmod +x fix-caddy-permissions.sh && ./fix-caddy-permissions.sh'
```
### 3. 创建日志目录
```bash
sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy
```
### 4. 验证配置
```bash
sudo caddy validate --config /etc/caddy/Caddyfile
```
### 5. 重新加载配置
```bash
sudo systemctl reload caddy
```
### 6. 检查状态
```bash
sudo systemctl status caddy
```
## 配置说明
### 基本功能
- **域名**: `photography.iriver.top`
- **根目录**: `~/www/photography`
- **自动 HTTPS**: Caddy 自动获取和续期 SSL 证书
- **文件服务**: 直接提供静态文件服务
### 优化功能
- **Gzip 压缩**: 减少传输大小
- **缓存控制**: 静态资源长期缓存HTML 短期缓存
- **安全头**: 防止常见安全问题
- **错误处理**: 404 错误重定向到 404.html
### 日志功能
- **位置**: `/var/log/caddy/photography.log`
- **格式**: JSON 格式便于分析
- **轮转**: 10MB 轮转,保留 5 个文件
## 故障排除
### 权限问题
如果遇到 `permission denied` 错误:
```bash
# 检查目录权限
ls -la /home/gitea/www/photography
# 运行权限修复脚本
./fix-caddy-permissions.sh
# 验证 caddy 用户可以访问
sudo -u caddy ls -la /home/gitea/www/photography
```
### 检查配置语法
```bash
caddy validate --config /path/to/Caddyfile
```
### 查看日志
```bash
# 系统日志
sudo journalctl -u caddy -f
# 应用日志
sudo tail -f /var/log/caddy/photography.log
```
### 测试配置
```bash
# 测试模式启动
sudo caddy run --config /etc/caddy/Caddyfile
```
### 常见错误解决
#### 1. Permission denied 错误
- **原因**: Caddy 进程无法访问用户目录
- **解决**: 运行 `fix-caddy-permissions.sh` 脚本
#### 2. 404 Not Found 错误
- **原因**: 文件路径不正确或文件不存在
- **解决**: 检查 `/home/gitea/www/photography` 目录是否有文件
#### 3. 证书获取失败
- **原因**: 域名 DNS 未正确指向服务器
- **解决**: 确认 DNS A 记录指向正确 IP
## 域名解析
确保域名 `photography.iriver.top` 的 DNS 记录指向服务器 IP
```
A photography.iriver.top YOUR_SERVER_IP
```
## SSL 证书
Caddy 会自动:
- 获取 Let's Encrypt SSL 证书
- 自动续期证书
- 强制 HTTPS 重定向
## 性能优化
配置包含以下优化:
- Gzip 压缩减少带宽
- 静态资源缓存提高加载速度
- 安全头提高安全性
- 错误页面友好处理

View File

@ -0,0 +1,29 @@
#!/bin/bash
# 修复 Caddy 访问 gitea 用户目录的权限问题
echo "🔧 修复 Caddy 权限问题..."
# 1. 确保目录存在
sudo -u gitea mkdir -p /home/gitea/www/photography
# 2. 设置目录权限,让 caddy 用户可以访问
# 给 gitea 主目录添加执行权限(让其他用户可以进入)
sudo chmod 755 /home/gitea
# 给 www 目录设置权限
sudo chmod 755 /home/gitea/www
# 给 photography 目录设置权限
sudo chmod 755 /home/gitea/www/photography
# 3. 设置文件权限
sudo find /home/gitea/www/photography -type f -exec chmod 644 {} \;
sudo find /home/gitea/www/photography -type d -exec chmod 755 {} \;
# 4. 检查 caddy 用户是否可以访问
echo "📋 检查权限..."
sudo -u caddy ls -la /home/gitea/www/photography || echo "⚠️ caddy 用户无法访问目录"
echo "✅ 权限修复完成!"
echo "🔄 请重新加载 Caddy 配置sudo systemctl reload caddy"