docs: 完善项目文档并清理过时文件
新增文档： - API_INTEGRATION_GUIDE.md: API集成指南（快速开始、SDK示例、常见场景） - DEPLOYMENT_GUIDE.md: 部署指南（环境要求、生产部署、Docker部署） - CONFIGURATION_GUIDE.md: 配置指南（环境配置、数据库、Redis、安全） - DEVELOPMENT_GUIDE.md: 开发指南（环境搭建、项目结构、开发规范） 文档更新： - api.md: 补充8个缺失的API端点（分享跟踪、回调、用户奖励） 文档清理： - 归档18个过时文档到 docs/archive/2026-03-04-cleanup/ - 删除3个调试文档（ralph-loop-*） 代码清理： - 删除4个.bak备份文件 - 删除1个.disabled测试文件 文档结构优化： - 从~40个文档精简到12个核心文档 - 建立清晰的文档导航体系 - 完善文档间的交叉引用
This commit is contained in:
Your Name
665
docs/DEPLOYMENT_GUIDE.md
Normal file
665
docs/DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,665 @@
|
||||
# 🚀 部署指南
|
||||
|
||||
> 版本: 1.0
|
||||
> 更新时间: 2026-03-04
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [环境要求](#环境要求)
|
||||
2. [快速部署](#快速部署)
|
||||
3. [生产环境部署](#生产环境部署)
|
||||
4. [Docker部署](#docker部署)
|
||||
5. [数据库迁移](#数据库迁移)
|
||||
6. [监控与日志](#监控与日志)
|
||||
7. [故障排查](#故障排查)
|
||||
|
||||
## 🔧 环境要求
|
||||
|
||||
### 最低要求
|
||||
|
||||
| 组件 | 版本要求 | 说明 |
|
||||
|------|----------|------|
|
||||
| Java | 17+ | 推荐使用OpenJDK 17或21 |
|
||||
| PostgreSQL | 12+ | 推荐使用14或15 |
|
||||
| Redis | 6.0+ | 生产环境必需 |
|
||||
| Maven | 3.8+ | 构建工具 |
|
||||
| 内存 | 2GB+ | 推荐4GB |
|
||||
| 磁盘 | 10GB+ | 包含日志和数据 |
|
||||
|
||||
### 推荐配置
|
||||
|
||||
**开发环境：**
|
||||
- CPU: 2核
|
||||
- 内存: 4GB
|
||||
- 磁盘: 20GB SSD
|
||||
|
||||
**生产环境：**
|
||||
- CPU: 4核+
|
||||
- 内存: 8GB+
|
||||
- 磁盘: 50GB+ SSD
|
||||
- 负载均衡器（可选）
|
||||
- 数据库主从复制（推荐）
|
||||
|
||||
## ⚡ 快速部署
|
||||
|
||||
### 1. 克隆代码
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-org/mosquito.git
|
||||
cd mosquito
|
||||
```
|
||||
|
||||
### 2. 配置数据库
|
||||
|
||||
```bash
|
||||
# 创建数据库
|
||||
psql -U postgres -c "CREATE DATABASE mosquito;"
|
||||
psql -U postgres -c "CREATE USER mosquito_user WITH PASSWORD 'your_password';"
|
||||
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE mosquito TO mosquito_user;"
|
||||
```
|
||||
|
||||
### 3. 配置环境变量
|
||||
|
||||
```bash
|
||||
# 复制配置模板
|
||||
cp src/main/resources/application-dev.yml.example src/main/resources/application-dev.yml
|
||||
|
||||
# 编辑配置文件
|
||||
vi src/main/resources/application-dev.yml
|
||||
```
|
||||
|
||||
### 4. 构建项目
|
||||
|
||||
```bash
|
||||
# 跳过测试快速构建
|
||||
mvn clean package -DskipTests
|
||||
|
||||
# 或者运行完整测试
|
||||
mvn clean package
|
||||
```
|
||||
|
||||
### 5. 启动应用
|
||||
|
||||
```bash
|
||||
java -jar target/mosquito-1.0.0.jar --spring.profiles.active=dev
|
||||
```
|
||||
|
||||
应用将在 `http://localhost:8080` 启动。
|
||||
|
||||
## 🏭 生产环境部署
|
||||
|
||||
### 1. 准备工作
|
||||
|
||||
**创建专用用户：**
|
||||
|
||||
```bash
|
||||
sudo useradd -r -s /bin/false mosquito
|
||||
sudo mkdir -p /opt/mosquito
|
||||
sudo chown mosquito:mosquito /opt/mosquito
|
||||
```
|
||||
|
||||
**配置PostgreSQL：**
|
||||
|
||||
```sql
|
||||
-- 创建生产数据库
|
||||
CREATE DATABASE mosquito_prod;
|
||||
CREATE USER mosquito_prod WITH PASSWORD 'strong_password_here';
|
||||
GRANT ALL PRIVILEGES ON DATABASE mosquito_prod TO mosquito_prod;
|
||||
|
||||
-- 配置连接池
|
||||
ALTER SYSTEM SET max_connections = 200;
|
||||
ALTER SYSTEM SET shared_buffers = '2GB';
|
||||
ALTER SYSTEM SET effective_cache_size = '6GB';
|
||||
SELECT pg_reload_conf();
|
||||
```
|
||||
|
||||
**配置Redis：**
|
||||
|
||||
```bash
|
||||
# 编辑Redis配置
|
||||
sudo vi /etc/redis/redis.conf
|
||||
|
||||
# 设置密码
|
||||
requirepass your_redis_password
|
||||
|
||||
# 设置最大内存
|
||||
maxmemory 1gb
|
||||
maxmemory-policy allkeys-lru
|
||||
|
||||
# 启用持久化
|
||||
save 900 1
|
||||
save 300 10
|
||||
save 60 10000
|
||||
|
||||
# 重启Redis
|
||||
sudo systemctl restart redis
|
||||
```
|
||||
|
||||
### 2. 配置应用
|
||||
|
||||
创建 `/opt/mosquito/application-prod.yml`：
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
url: jdbc:postgresql://localhost:5432/mosquito_prod
|
||||
username: mosquito_prod
|
||||
password: ${DB_PASSWORD}
|
||||
hikari:
|
||||
maximum-pool-size: 20
|
||||
minimum-idle: 5
|
||||
connection-timeout: 30000
|
||||
idle-timeout: 600000
|
||||
max-lifetime: 1800000
|
||||
|
||||
data:
|
||||
redis:
|
||||
host: localhost
|
||||
port: 6379
|
||||
password: ${REDIS_PASSWORD}
|
||||
lettuce:
|
||||
pool:
|
||||
max-active: 20
|
||||
max-idle: 10
|
||||
min-idle: 5
|
||||
|
||||
flyway:
|
||||
enabled: true
|
||||
baseline-on-migrate: true
|
||||
|
||||
app:
|
||||
api-key:
|
||||
encryption-key: ${API_KEY_ENCRYPTION_KEY}
|
||||
rate-limit:
|
||||
per-minute: 100
|
||||
poster:
|
||||
cache-enabled: true
|
||||
|
||||
logging:
|
||||
level:
|
||||
root: INFO
|
||||
com.mosquito.project: INFO
|
||||
file:
|
||||
name: /var/log/mosquito/application.log
|
||||
max-size: 100MB
|
||||
max-history: 30
|
||||
```
|
||||
|
||||
### 3. 创建systemd服务
|
||||
|
||||
创建 `/etc/systemd/system/mosquito.service`：
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Mosquito Activity Tracking Service
|
||||
After=network.target postgresql.service redis.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=mosquito
|
||||
Group=mosquito
|
||||
WorkingDirectory=/opt/mosquito
|
||||
|
||||
Environment="JAVA_OPTS=-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"
|
||||
Environment="DB_PASSWORD=your_db_password"
|
||||
Environment="REDIS_PASSWORD=your_redis_password"
|
||||
Environment="API_KEY_ENCRYPTION_KEY=your_32_char_encryption_key"
|
||||
|
||||
ExecStart=/usr/bin/java $JAVA_OPTS \
|
||||
-jar /opt/mosquito/mosquito-1.0.0.jar \
|
||||
--spring.profiles.active=prod \
|
||||
--spring.config.location=/opt/mosquito/application-prod.yml
|
||||
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### 4. 部署应用
|
||||
|
||||
```bash
|
||||
# 复制JAR文件
|
||||
sudo cp target/mosquito-1.0.0.jar /opt/mosquito/
|
||||
sudo chown mosquito:mosquito /opt/mosquito/mosquito-1.0.0.jar
|
||||
|
||||
# 创建日志目录
|
||||
sudo mkdir -p /var/log/mosquito
|
||||
sudo chown mosquito:mosquito /var/log/mosquito
|
||||
|
||||
# 重新加载systemd
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
# 启动服务
|
||||
sudo systemctl start mosquito
|
||||
|
||||
# 设置开机自启
|
||||
sudo systemctl enable mosquito
|
||||
|
||||
# 检查状态
|
||||
sudo systemctl status mosquito
|
||||
```
|
||||
|
||||
### 5. 配置Nginx反向代理
|
||||
|
||||
创建 `/etc/nginx/sites-available/mosquito`：
|
||||
|
||||
```nginx
|
||||
upstream mosquito_backend {
|
||||
server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
|
||||
keepalive 32;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name api.example.com;
|
||||
|
||||
# 重定向到HTTPS
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name api.example.com;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||
|
||||
access_log /var/log/nginx/mosquito_access.log;
|
||||
error_log /var/log/nginx/mosquito_error.log;
|
||||
|
||||
client_max_body_size 10M;
|
||||
|
||||
location / {
|
||||
proxy_pass http://mosquito_backend;
|
||||
proxy_http_version 1.1;
|
||||
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header Connection "";
|
||||
|
||||
proxy_connect_timeout 30s;
|
||||
proxy_send_timeout 30s;
|
||||
proxy_read_timeout 30s;
|
||||
|
||||
proxy_buffering on;
|
||||
proxy_buffer_size 4k;
|
||||
proxy_buffers 8 4k;
|
||||
}
|
||||
|
||||
location /actuator/health {
|
||||
proxy_pass http://mosquito_backend;
|
||||
access_log off;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
启用配置：
|
||||
|
||||
```bash
|
||||
sudo ln -s /etc/nginx/sites-available/mosquito /etc/nginx/sites-enabled/
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
## 🐳 Docker部署
|
||||
|
||||
### 1. Dockerfile
|
||||
|
||||
创建 `Dockerfile`：
|
||||
|
||||
```dockerfile
|
||||
FROM eclipse-temurin:17-jre-alpine
|
||||
|
||||
LABEL maintainer="your-email@example.com"
|
||||
LABEL version="1.0.0"
|
||||
|
||||
# 创建应用目录
|
||||
WORKDIR /app
|
||||
|
||||
# 复制JAR文件
|
||||
COPY target/mosquito-1.0.0.jar app.jar
|
||||
|
||||
# 创建非root用户
|
||||
RUN addgroup -S mosquito && adduser -S mosquito -G mosquito
|
||||
RUN chown -R mosquito:mosquito /app
|
||||
USER mosquito
|
||||
|
||||
# 健康检查
|
||||
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
|
||||
CMD wget --no-verbose --tries=1 --spider http://localhost:8080/actuator/health || exit 1
|
||||
|
||||
# 暴露端口
|
||||
EXPOSE 8080
|
||||
|
||||
# JVM参数
|
||||
ENV JAVA_OPTS="-Xms512m -Xmx1g -XX:+UseG1GC"
|
||||
|
||||
# 启动命令
|
||||
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]
|
||||
```
|
||||
|
||||
### 2. Docker Compose
|
||||
|
||||
创建 `docker-compose.yml`：
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15-alpine
|
||||
container_name: mosquito-postgres
|
||||
environment:
|
||||
POSTGRES_DB: mosquito
|
||||
POSTGRES_USER: mosquito
|
||||
POSTGRES_PASSWORD: ${DB_PASSWORD}
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
ports:
|
||||
- "5432:5432"
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U mosquito"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
container_name: mosquito-redis
|
||||
command: redis-server --requirepass ${REDIS_PASSWORD}
|
||||
volumes:
|
||||
- redis_data:/data
|
||||
ports:
|
||||
- "6379:6379"
|
||||
healthcheck:
|
||||
test: ["CMD", "redis-cli", "ping"]
|
||||
interval: 10s
|
||||
timeout: 3s
|
||||
retries: 5
|
||||
|
||||
app:
|
||||
build: .
|
||||
container_name: mosquito-app
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
environment:
|
||||
SPRING_PROFILES_ACTIVE: prod
|
||||
SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/mosquito
|
||||
SPRING_DATASOURCE_USERNAME: mosquito
|
||||
SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
|
||||
SPRING_DATA_REDIS_HOST: redis
|
||||
SPRING_DATA_REDIS_PASSWORD: ${REDIS_PASSWORD}
|
||||
API_KEY_ENCRYPTION_KEY: ${API_KEY_ENCRYPTION_KEY}
|
||||
ports:
|
||||
- "8080:8080"
|
||||
volumes:
|
||||
- app_logs:/app/logs
|
||||
restart: unless-stopped
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
redis_data:
|
||||
app_logs:
|
||||
```
|
||||
|
||||
### 3. 启动Docker环境
|
||||
|
||||
```bash
|
||||
# 创建.env文件
|
||||
cat > .env << EOF
|
||||
DB_PASSWORD=your_db_password
|
||||
REDIS_PASSWORD=your_redis_password
|
||||
API_KEY_ENCRYPTION_KEY=your_32_char_encryption_key
|
||||
EOF
|
||||
|
||||
# 构建镜像
|
||||
docker-compose build
|
||||
|
||||
# 启动服务
|
||||
docker-compose up -d
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs -f app
|
||||
|
||||
# 检查状态
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
## 🗄️ 数据库迁移
|
||||
|
||||
### Flyway自动迁移
|
||||
|
||||
应用启动时会自动执行Flyway迁移：
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
flyway:
|
||||
enabled: true
|
||||
baseline-on-migrate: true
|
||||
locations: classpath:db/migration
|
||||
```
|
||||
|
||||
### 手动迁移
|
||||
|
||||
```bash
|
||||
# 查看迁移状态
|
||||
mvn flyway:info
|
||||
|
||||
# 执行迁移
|
||||
mvn flyway:migrate
|
||||
|
||||
# 回滚（需要Flyway Pro）
|
||||
mvn flyway:undo
|
||||
```
|
||||
|
||||
### 迁移脚本位置
|
||||
|
||||
```
|
||||
src/main/resources/db/migration/
|
||||
├── V1__Create_activities_table.sql
|
||||
├── V2__Create_api_keys_table.sql
|
||||
├── V3__Create_daily_activity_stats_table.sql
|
||||
├── ...
|
||||
└── V20__Add_share_tracking_fields.sql
|
||||
```
|
||||
|
||||
### 生产环境迁移最佳实践
|
||||
|
||||
1. **备份数据库**
|
||||
|
||||
```bash
|
||||
pg_dump -U mosquito_prod -h localhost mosquito_prod > backup_$(date +%Y%m%d_%H%M%S).sql
|
||||
```
|
||||
|
||||
2. **在测试环境验证**
|
||||
|
||||
```bash
|
||||
# 恢复到测试环境
|
||||
psql -U mosquito_test -h localhost mosquito_test < backup.sql
|
||||
|
||||
# 运行迁移
|
||||
mvn flyway:migrate -Dflyway.url=jdbc:postgresql://localhost:5432/mosquito_test
|
||||
```
|
||||
|
||||
3. **执行生产迁移**
|
||||
|
||||
```bash
|
||||
# 停止应用（可选，取决于迁移类型）
|
||||
sudo systemctl stop mosquito
|
||||
|
||||
# 执行迁移
|
||||
mvn flyway:migrate -Dflyway.url=jdbc:postgresql://localhost:5432/mosquito_prod
|
||||
|
||||
# 启动应用
|
||||
sudo systemctl start mosquito
|
||||
```
|
||||
|
||||
## 📊 监控与日志
|
||||
|
||||
### Spring Boot Actuator
|
||||
|
||||
启用健康检查和指标：
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: health,info,metrics,prometheus
|
||||
endpoint:
|
||||
health:
|
||||
show-details: when-authorized
|
||||
```
|
||||
|
||||
访问端点：
|
||||
- 健康检查: `http://localhost:8080/actuator/health`
|
||||
- 指标: `http://localhost:8080/actuator/metrics`
|
||||
- Prometheus: `http://localhost:8080/actuator/prometheus`
|
||||
|
||||
### 日志配置
|
||||
|
||||
`logback-spring.xml`：
|
||||
|
||||
```xml
|
||||
<configuration>
|
||||
<springProfile name="prod">
|
||||
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
|
||||
<file>/var/log/mosquito/application.log</file>
|
||||
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
|
||||
<fileNamePattern>/var/log/mosquito/application.%d{yyyy-MM-dd}.log</fileNamePattern>
|
||||
<maxHistory>30</maxHistory>
|
||||
<totalSizeCap>10GB</totalSizeCap>
|
||||
</rollingPolicy>
|
||||
<encoder>
|
||||
<pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
|
||||
</encoder>
|
||||
</appender>
|
||||
|
||||
<root level="INFO">
|
||||
<appender-ref ref="FILE" />
|
||||
</root>
|
||||
</springProfile>
|
||||
</configuration>
|
||||
```
|
||||
|
||||
### 监控工具集成
|
||||
|
||||
**Prometheus + Grafana：**
|
||||
|
||||
```yaml
|
||||
# prometheus.yml
|
||||
scrape_configs:
|
||||
- job_name: 'mosquito'
|
||||
metrics_path: '/actuator/prometheus'
|
||||
static_configs:
|
||||
- targets: ['localhost:8080']
|
||||
```
|
||||
|
||||
## 🔍 故障排查
|
||||
|
||||
### 常见问题
|
||||
|
||||
**1. 应用无法启动**
|
||||
|
||||
```bash
|
||||
# 检查日志
|
||||
sudo journalctl -u mosquito -n 100 --no-pager
|
||||
|
||||
# 检查端口占用
|
||||
sudo netstat -tlnp | grep 8080
|
||||
|
||||
# 检查数据库连接
|
||||
psql -U mosquito_prod -h localhost -d mosquito_prod -c "SELECT 1;"
|
||||
```
|
||||
|
||||
**2. Redis连接失败**
|
||||
|
||||
```bash
|
||||
# 检查Redis状态
|
||||
sudo systemctl status redis
|
||||
|
||||
# 测试连接
|
||||
redis-cli -a your_redis_password ping
|
||||
|
||||
# 检查配置
|
||||
redis-cli -a your_redis_password CONFIG GET requirepass
|
||||
```
|
||||
|
||||
**3. 数据库迁移失败**
|
||||
|
||||
```bash
|
||||
# 查看Flyway状态
|
||||
mvn flyway:info
|
||||
|
||||
# 修复失败的迁移
|
||||
mvn flyway:repair
|
||||
|
||||
# 手动执行SQL
|
||||
psql -U mosquito_prod -h localhost -d mosquito_prod -f src/main/resources/db/migration/V20__xxx.sql
|
||||
```
|
||||
|
||||
**4. 内存不足**
|
||||
|
||||
```bash
|
||||
# 查看JVM内存使用
|
||||
jcmd <pid> VM.native_memory summary
|
||||
|
||||
# 调整JVM参数
|
||||
sudo vi /etc/systemd/system/mosquito.service
|
||||
# 修改: Environment="JAVA_OPTS=-Xms2g -Xmx4g"
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart mosquito
|
||||
```
|
||||
|
||||
### 性能调优
|
||||
|
||||
**JVM参数优化：**
|
||||
|
||||
```bash
|
||||
JAVA_OPTS="
|
||||
-Xms2g -Xmx4g
|
||||
-XX:+UseG1GC
|
||||
-XX:MaxGCPauseMillis=200
|
||||
-XX:+HeapDumpOnOutOfMemoryError
|
||||
-XX:HeapDumpPath=/var/log/mosquito/heapdump.hprof
|
||||
-XX:+PrintGCDetails
|
||||
-XX:+PrintGCDateStamps
|
||||
-Xloggc:/var/log/mosquito/gc.log
|
||||
"
|
||||
```
|
||||
|
||||
**数据库连接池：**
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
hikari:
|
||||
maximum-pool-size: 20
|
||||
minimum-idle: 5
|
||||
connection-timeout: 30000
|
||||
idle-timeout: 600000
|
||||
max-lifetime: 1800000
|
||||
```
|
||||
|
||||
## 📚 相关资源
|
||||
|
||||
- [配置指南](./CONFIGURATION_GUIDE.md) - 详细配置说明
|
||||
- [API文档](./api.md) - API接口文档
|
||||
- [开发指南](./DEVELOPMENT_GUIDE.md) - 开发环境搭建
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: 1.0
|
||||
**最后更新**: 2026-03-04
|
||||
Reference in New Issue
Block a user