docs: 运维手册 + 更新上线部署方案

.claude/plan/java-deployment.md

@@ -50,7 +50,7 @@ logging:
 
 ---
 
-## Step 2: 推送代码到服务器
+## Step 2: 推送 + 服务器切分支
 
 本地：
 ```bash
@@ -63,8 +63,10 @@ git push origin java
 服务器：
 ```bash
 cd /root/payments/code/payment-platform
-git fetch origin java
+git stash                        # 备份本地改动（如有）
+git fetch origin
 git checkout java
+git pull origin java             # 拿到最新 java 分支
 ```
 
 ---
@@ -82,18 +84,25 @@ done
 
 ---
 
-## Step 4: 构建 Java 镜像
+## Step 4: 本地构建 → 传服务器
 
+**本地：**
+```bash
+cd D:\project2\payment-platform\java
+mvn package -DskipTests
+
+# 重命名为 app.jar（Dockerfile.runtime 期望此名）
+cp target/*.jar target/app.jar
+
+# 传 JAR + runtime Dockerfile 到服务器
+scp target/app.jar root@<server>:/root/payments/code/payment-platform/java/target/app.jar
+scp Dockerfile.runtime root@<server>:/root/payments/code/payment-platform/java/Dockerfile.runtime
+```
+
+**服务器（轻量 docker build，不跑 Maven）：**
 ```bash
 cd /root/payments/code/payment-platform/java
-docker run --rm \
-  -v "$PWD":/app \
-  -v "$HOME/.m2":/root/.m2 \
-  -w /app \
-  maven:3.9-eclipse-temurin-21-alpine \
-  mvn package -DskipTests
-
-docker build -t xjz/java-backend:1.0.0 .
+docker build -f Dockerfile -t xjz/java-backend:1.0.0 .
 ```
 
 ---

.claude/plan/ops-manual.md

@@ -0,0 +1,163 @@
+# 支付平台运维手册
+
+## 服务器信息
+
+- IP: `172.20.205.37`
+- 域名: `qcsj88888.com`、`api.qcsj88888.com`
+- 系统: Ubuntu (Alibaba Cloud ECS)
+
+## 容器拓扑
+
+| 容器 | 镜像 | 端口 | 网络 |
+|---|---|---|---|
+| java-backend | xjz/java-backend:1.0.0 | 8001 | app-tier, deploy_app-tier |
+| frontend | xjz/frontend:2.5.4 | 5173→80 | app-tier |
+| postgres | postgres:18.3 | 127.0.0.1:5432 | 宿主机, deploy_app-tier |
+| redis | redis:8.6.2-alpine | 6379 | deploy_app-tier |
+| nginx-proxy-manager | jc21/nginx-proxy-manager | 80/443/81 | deploy_app-tier |
+| gogs | gogs/gogs | 3000/2222 | deploy_app-tier |
+
+```
+qcsj88888.com (HTTPS)
+    ↓ NPM
+    ├── /api/v1/* → java-backend:8001
+    └── 其余 → frontend:5173
+```
+
+## 项目路径
+
+- 代码: `/root/payments/code/payment-platform`
+- Compose: `/root/payments/code/payment-platform/docker-compose.yml`
+- NPM 数据: `/root/payments/deploy/nginx-proxy-manager/data`
+
+## 常用操作
+
+### 查看容器状态
+
+```bash
+cd /root/payments/code/payment-platform
+docker compose ps
+docker stats --no-stream
+```
+
+### 查看日志
+
+```bash
+docker compose logs java-backend --tail 50       # 最近50行
+docker compose logs java-backend -f               # 实时跟踪
+docker compose logs java-backend --since 5m       # 最近5分钟
+```
+
+### 重启后端
+
+```bash
+docker compose restart java-backend
+```
+
+### 停止/启动
+
+```bash
+docker compose stop java-backend
+docker compose start java-backend
+```
+
+### 健康检查
+
+```bash
+curl http://localhost:8001/api/v1/payment/notify/health
+# 预期返回: {"code":0,"data":{"status":"ok"}}
+```
+
+## 升级部署
+
+```bash
+# === 本地 ===
+cd D:\project2\payment-platform\java
+mvn clean package -DskipTests
+scp target/payment-platform-1.0.0.jar root@172.20.205.37:/root/payments/code/payment-platform/java/target/
+
+# === 服务器 ===
+cd /root/payments/code/payment-platform/java
+docker build -t xjz/java-backend:1.0.0 .
+cd ..
+docker compose up -d java-backend
+docker compose logs java-backend --tail 20 -f
+```
+
+## 数据库迁移
+
+新增 SQL 脚本放在 `java/sql/`，服务器执行：
+
+```bash
+docker exec -i postgres psql -U admin -d payment_platform_prod < /root/payments/code/payment-platform/java/sql/xxx.sql
+```
+
+## 回滚到 Python
+
+```bash
+docker stop java-backend
+docker rm java-backend
+cd /root/payments/code/payment-platform
+git checkout master
+docker compose up -d backend
+```
+
+## 配置说明
+
+### JVM 参数
+
+```yaml
+JAVA_OPTS: "-Xms128m -Xmx256m -XX:+UseSerialGC -XX:MaxRAMPercentage=50 -XX:TieredStopAtLevel=1"
+```
+
+- `-Xms128m`: 初始堆 128MB
+- `-Xmx256m`: 最大堆 256MB
+- `-XX:+UseSerialGC`: 单线程 GC（2C 服务器避免并发 GC 开销）
+- `-XX:MaxRAMPercentage=50`: JVM 最多用 50% 物理内存
+- `-XX:TieredStopAtLevel=1`: 减少 JIT 编译层级，启动更快
+
+### 环境变量（数据库/Redis）
+
+```yaml
+SPRING_DATASOURCE_DRUID_URL: jdbc:postgresql://postgres:5432/payment_platform_prod?currentSchema=public
+SPRING_DATASOURCE_DRUID_USERNAME: admin
+SPRING_DATASOURCE_DRUID_PASSWORD: 'xjz#123321'
+SPRING_DATA_REDIS_HOST: redis
+SPRING_DATA_REDIS_PORT: 6379
+SPRING_DATA_REDIS_DATABASE: 0
+SPRING_DATA_REDIS_PASSWORD: '123456#xjz'
+```
+
+## 故障排查
+
+### 后端起不来
+
+```bash
+docker compose logs java-backend --tail 100
+```
+
+常见原因：
+- `Connection refused: postgres:5432` → postgres 没加入 deploy_app-tier，执行 `docker network connect deploy_app-tier postgres`
+- `OutOfMemoryError` → 调大 `-Xmx` 到 384m
+- 端口占用 → `lsof -i:8001`，停掉占用进程
+
+### 页面访问 502
+
+检查后端是否正常：
+```bash
+curl http://localhost:8001/api/v1/payment/notify/health
+```
+后端正常则查 NPM 是否在线：`docker ps | grep nginx-proxy-manager`
+
+### 磁盘空间
+
+```bash
+docker system prune -a --filter "until=72h"  # 清理72小时前的旧镜像
+```
+
+## 备份
+
+```bash
+# 数据库
+docker exec postgres pg_dump -U admin payment_platform_prod > /root/backup/payment_$(date +%Y%m%d).sql
+```