wenzi/docs/DEPLOYMENT_GUIDE.md

🚀 部署指南

版本: 1.0 更新时间: 2026-03-04

📋 目录

1. 环境要求
2. 快速部署
3. 生产环境部署
4. 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. 克隆代码

git clone https://github.com/your-org/mosquito.git
cd mosquito

2. 配置数据库

# 创建数据库
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. 配置环境变量

# 复制配置模板
cp src/main/resources/application-dev.yml.example src/main/resources/application-dev.yml

# 编辑配置文件
vi src/main/resources/application-dev.yml

4. 构建项目

# 跳过测试快速构建
mvn clean package -DskipTests

# 或者运行完整测试
mvn clean package

5. 启动应用

java -jar target/mosquito-1.0.0.jar --spring.profiles.active=dev

应用将在 http://localhost:8080 启动。

🏭 生产环境部署

1. 准备工作

创建专用用户：

sudo useradd -r -s /bin/false mosquito
sudo mkdir -p /opt/mosquito
sudo chown mosquito:mosquito /opt/mosquito

配置PostgreSQL：

-- 创建生产数据库
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：

# 编辑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：

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：

[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. 部署应用

# 复制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：

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;
    }
}

启用配置：

sudo ln -s /etc/nginx/sites-available/mosquito /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

🐳 Docker部署

1. 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：

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环境

# 创建.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迁移：

spring:
  flyway:
    enabled: true
    baseline-on-migrate: true
    locations: classpath:db/migration

手动迁移

# 查看迁移状态
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. 备份数据库

pg_dump -U mosquito_prod -h localhost mosquito_prod > backup_$(date +%Y%m%d_%H%M%S).sql

2. 在测试环境验证

# 恢复到测试环境
psql -U mosquito_test -h localhost mosquito_test < backup.sql

# 运行迁移
mvn flyway:migrate -Dflyway.url=jdbc:postgresql://localhost:5432/mosquito_test

3. 执行生产迁移

# 停止应用（可选，取决于迁移类型）
sudo systemctl stop mosquito

# 执行迁移
mvn flyway:migrate -Dflyway.url=jdbc:postgresql://localhost:5432/mosquito_prod

# 启动应用
sudo systemctl start mosquito

📊 监控与日志

Spring Boot Actuator

启用健康检查和指标：

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：

<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：

# prometheus.yml
scrape_configs:
  - job_name: 'mosquito'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['localhost:8080']

🔍 故障排查

常见问题

1. 应用无法启动

# 检查日志
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连接失败

# 检查Redis状态
sudo systemctl status redis

# 测试连接
redis-cli -a your_redis_password ping

# 检查配置
redis-cli -a your_redis_password CONFIG GET requirepass

3. 数据库迁移失败

# 查看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. 内存不足

# 查看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参数优化：

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
"

数据库连接池：

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

📚 相关资源

• 配置指南 - 详细配置说明
• API文档 - API接口文档
• 开发指南 - 开发环境搭建

---

文档版本: 1.0 最后更新: 2026-03-04