# 智价云（药店版） - 部署文档

> **⚠️ MVP 阶段说明**  
> 本项目为**全新项目，尚未上线**，当前处于 **MVP（最小可行产品）阶段**。  
> 本文档描述的是 MVP 版本的部署方案，生产环境部署前需完成性能优化和安全加固。
>
> 版本：v1.0-MVP | 更新日期：2026-06-16 | 状态：开发中

---

## 1. 环境要求

### 1.1 基础环境

| 组件 | 最低版本 | 推荐版本 | 说明 |
|------|----------|----------|------|
| JDK | 17 | 17.0.x LTS | 必须，Spring Boot 3.x 要求 |
| Maven | 3.8 | 3.9+ | 构建工具 |
| MySQL | 8.0 | 8.0.33+ | 主数据库 |
| Redis | 6.0 | 7.0+ | 缓存、限流、验证码 |

### 1.2 硬件建议

| 环境 | CPU | 内存 | 磁盘 |
|------|-----|------|------|
| 开发环境 | 2核 | 4GB | 20GB |
| 测试环境 | 4核 | 8GB | 50GB |
| 生产环境 | 8核 | 16GB | 100GB SSD |

---

## 2. 中间件安装

### 2.1 MySQL 8.0

```bash
# 安装 MySQL 8.0
# Windows: 下载 MySQL Installer
# Linux:
sudo apt install mysql-server-8.0

# 创建数据库
mysql -u root -p
CREATE DATABASE zhijiayun_pharmacy
    DEFAULT CHARACTER SET utf8mb4
    DEFAULT COLLATE utf8mb4_unicode_ci;

# 创建应用用户（生产环境建议不使用root）
CREATE USER 'zhijiayun'@'%' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON zhijiayun_pharmacy.* TO 'zhijiayun'@'%';
FLUSH PRIVILEGES;
```

### 2.2 Redis

```bash
# Windows: 使用 Memurai 或 WSL 安装
# Linux:
sudo apt install redis-server

# 配置密码（生产环境必须）
# 编辑 /etc/redis/redis.conf
requirepass your_redis_password

# 启动
sudo systemctl start redis
sudo systemctl enable redis
```

---

## 3. 配置说明

### 3.1 配置文件

主配置文件：`zhijiayun-gateway/src/main/resources/application.yml`

### 3.2 数据库配置

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/zhijiayun_pharmacy?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true&rewriteBatchedStatements=true
    username: zhijiayun
    password: your_secure_password
    hikari:
      minimum-idle: 5
      maximum-pool-size: 20
      idle-timeout: 300000
      max-lifetime: 1800000
      connection-timeout: 30000
```

### 3.3 Redis 配置

```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: your_redis_password
      database: 0
      timeout: 5000ms
      lettuce:
        pool:
          max-active: 16
          max-idle: 8
          min-idle: 2
          max-wait: 3000ms
```

### 3.4 JWT 配置

```yaml
jwt:
  secret: YourSuperSecretKeyForJWTTokenGenerationMustBeAtLeast256BitsLong!!  # 生产环境必须更换
  expiration: 86400000       # 24小时
  refresh-expiration: 604800000  # 7天
```

> **重要**：生产环境必须替换 `jwt.secret`，建议使用 256 位以上随机字符串。

### 3.5 阿里云短信配置

```yaml
sms:
  access-key-id: ${ALIBABA_CLOUD_ACCESS_KEY_ID}
  access-key-secret: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET}
  sign-name: 知家云药房
  template-code: SMS_000000
```

> 通过环境变量注入 AK/SK，不要硬编码在配置文件中。

### 3.6 微信开放平台配置

```yaml
wechat:
  open:
    app-id: your_wechat_app_id
    app-secret: your_wechat_app_secret
    qr-connect:
      redirect-uri: https://your-domain.com/api/auth/wechat/callback
      scope: snsapi_login
```

---

## 4. 构建与启动

### 4.1 编译构建

```bash
# 在项目根目录执行
mvn clean package -DskipTests

# 产物位置
# zhijiayun-gateway/target/zhijiayun-gateway-1.0.0.jar
```

### 4.2 本地启动

```bash
# 方式一：Maven 直接运行
mvn spring-boot:run -pl zhijiayun-gateway

# 方式二：运行 JAR
java -jar zhijiayun-gateway/target/zhijiayun-gateway-1.0.0.jar

# 方式三：指定配置文件
java -jar zhijiayun-gateway/target/zhijiayun-gateway-1.0.0.jar \
  --spring.datasource.url=jdbc:mysql://prod-db:3306/zhijiayun_pharmacy \
  --spring.data.redis.host=prod-redis
```

### 4.3 生产环境启动

```bash
# 使用环境变量
export ALIBABA_CLOUD_ACCESS_KEY_ID=your_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_key_secret

# JVM 参数启动
java -Xms2g -Xmx4g \
  -Dspring.profiles.active=prod \
  -jar zhijiayun-gateway-1.0.0.jar \
  > /var/log/zhijiayun/app.log 2>&1 &
```

### 4.4 Systemd 服务（Linux）

```ini
# /etc/systemd/system/zhijiayun.service
[Unit]
Description=Zhijiayun Pharmacy Application
After=network.target mysql.service redis.service

[Service]
Type=simple
User=zhijiayun
WorkingDirectory=/opt/zhijiayun
ExecStart=/usr/bin/java -Xms2g -Xmx4g -jar zhijiayun-gateway-1.0.0.jar
Restart=always
RestartSec=10
Environment=ALIBABA_CLOUD_ACCESS_KEY_ID=your_key_id
Environment=ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_key_secret

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable zhijiayun
sudo systemctl start zhijiayun
sudo systemctl status zhijiayun
```

### 4.5 生产环境部署步骤（服务器 8.135.32.236）

当前生产环境（236 服务器）采用「本地打包 → scp 上传 → deploy.sh 重启」的裸机部署方式，不使用 Docker。

**部署环境信息**

| 项目 | 值 |
|------|-----|
| 服务器 | `root@8.135.32.236` |
| SSH 私钥 | `D:\project\D2D\docs\d2d.pem` |
| 部署目录 | `/opt` |
| 产物 JAR | `/opt/zhijiayun-gateway-1.0.0.jar` |
| 部署脚本 | `/opt/deploy.sh`（start/stop/restart/status/build/logs） |
| 环境变量 | `/opt/.env` |
| PID 文件 | `/opt/zhijiayun-pharmacy.pid` |
| 日志目录 | `/opt/logs/zhijiayun-pharmacy` |
| 应用端口 | `8002`（健康检查 `/actuator/health`） |
| 启动 Profile | `prod` |

**步骤 1：本地打包**

```bash
cd D:\kailin-zuoti\projet-zuoti\zhijiayun-pharmacy
mvn clean package -pl zhijiayun-gateway -am -DskipTests
# 产物：zhijiayun-gateway\target\zhijiayun-gateway-1.0.0.jar
```

> 说明：必须带 `-pl zhijiayun-gateway -am`，会连同依赖模块（quiz/common/user）一起构建；不要只用 `-DskipTests` 裸打包。

**步骤 2：上传 JAR 到服务器**

```bash
scp -i "D:\project\D2D\docs\d2d.pem" -o StrictHostKeyChecking=no `
  "D:\kailin-zuoti\projet-zuoti\zhijiayun-pharmacy\zhijiayun-gateway\target\zhijiayun-gateway-1.0.0.jar" `
  root@8.135.32.236:/opt/zhijiayun-gateway-1.0.0.jar.new
```

> 先上传为 `.jar.new`，避免直接覆盖正在运行的 JAR 导致中断。

**步骤 3：覆盖 JAR 并重启**

```bash
ssh -i "D:\project\D2D\docs\d2d.pem" -o StrictHostKeyChecking=no root@8.135.32.236 `
  "mv /opt/zhijiayun-gateway-1.0.0.jar.new /opt/zhijiayun-gateway-1.0.0.jar && cd /opt && ./deploy.sh restart"
```

`deploy.sh restart` 会自动：停止旧进程 → 加载 `/opt/.env` → 启动新 JAR → 健康检查（最多 60 秒）。

**步骤 4：验证**

```bash
ssh -i "D:\project\D2D\docs\d2d.pem" -o StrictHostKeyChecking=no root@8.135.32.236 "cd /opt && ./deploy.sh status"
# 或直接健康检查
curl http://8.135.32.236:8002/actuator/health
```

**注意事项**

- `/opt/.env` 必须包含 `JWT_SECRET`、`DB_PASSWORD`、`REDIS_PASSWORD`、`ALIBABA_CLOUD_ACCESS_KEY_ID`、`ALIBABA_CLOUD_ACCESS_KEY_SECRET` 等必填项，`deploy.sh` 启动前会校验。
- `JWT_SECRET` 固定使用 `application-prod.yml` 中的默认值（`YourSuperSecretKeyForJWTTokenGenerationMustBeAtLeast256BitsLong!!`），**不要随意变更**，否则老用户缓存的 token 会全部失效。
- 历史 JAR 备份：`/opt/zhijiayun-gateway-1.0.0.jar.bak.`（每次上线前已备份，无需重复备份）。

---

## 5. 数据库初始化

### 5.1 自动初始化

应用启动时自动执行 `schema.sql` 建表脚本（通过 `spring.sql.init` 配置）。

### 5.2 初始化数据

默认等级数据随 schema.sql 自动插入：

| 等级 | 每日配额 | 每月配额 |
|------|----------|----------|
| 普通用户 (NORMAL) | 5 | 100 |
| VIP会员 (VIP) | 20 | 500 |
| SVIP会员 (SVIP) | 100 | 3000 |

---

## 6. 健康检查

### 6.1 应用端口

默认端口：`8080`

### 6.2 健康检查接口

```bash
curl http://localhost:8080/actuator/health
```

### 6.3 日志位置

| 环境 | 日志路径 |
|------|----------|
| 开发 | 控制台输出 |
| 生产 | /var/log/zhijiayun/app.log |

---

## 7. Nginx 反向代理（可选）

```nginx
upstream zhijiayun {
    server 127.0.0.1:8080;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate     /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    location / {
        proxy_pass http://zhijiayun;
        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;
    }
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}
```

---

## 8. 生产环境检查清单

| 检查项 | 状态 |
|--------|------|
| MySQL 连接池配置合理 | ☐ |
| Redis 密码已设置 | ☐ |
| JWT Secret 已更换为随机字符串 | ☐ |
| AK/SK 通过环境变量注入 | ☐ |
| 微信回调地址已更新为生产域名 | ☐ |
| HTTPS 证书已配置 | ☐ |
| 日志输出到文件并配置轮转 | ☐ |
| 数据库备份策略已制定 | ☐ |
| 限流参数已根据实际流量调整 | ☐ |
| JVM 内存参数已设置 | ☐ |