运维(#101): 新增测试环境 MinIO 上传链路配置

Co-authored-by: multica-agent <github@multica.ai>

.env.example

@@ -10,6 +10,12 @@ GRAFANA_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
 # PPanel Server 镜像标签（由 CI/CD 传入不可变 tag，如 git SHA）
 PPANEL_SERVER_TAG=CHANGE_ME_TO_GIT_SHA
 
+# 测试环境 MinIO / S3 兼容存储
+# ppanel.yaml 中 S3.Endpoint 使用 http://127.0.0.1:9000，Bucket 与此处保持一致。
+MINIO_ROOT_USER=CHANGE_ME_TO_S3_ACCESS_KEY
+MINIO_ROOT_PASSWORD=CHANGE_ME_TO_S3_SECRET_KEY
+MINIO_BUCKET=hifastvpn
+
 # AWS 区域（香港）
 AWS_REGION=ap-east-1
 

docker-compose.cloud.yml

@@ -40,6 +40,8 @@ services:
     depends_on:
       tempo:
         condition: service_started
+      minio:
+        condition: service_healthy
     logging:
       driver: "json-file"
       options:
@@ -239,6 +241,63 @@ services:
         max-size: "10m"
         max-file: "3"
 
+  # ----------------------------------------------------
+  # 10. MinIO (测试环境 S3 兼容对象存储)
+  #     仅绑定宿主机 127.0.0.1，供 host 网络的 ppanel-server 访问，不对公网开放。
+  # ----------------------------------------------------
+  minio:
+    image: minio/minio:RELEASE.2025-05-24T17-08-30Z-cpuv1
+    container_name: ppanel-minio
+    restart: always
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: "${MINIO_ROOT_USER:?请在 .env 文件中设置 MINIO_ROOT_USER}"
+      MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:?请在 .env 文件中设置 MINIO_ROOT_PASSWORD}"
+      TZ: Asia/Shanghai
+    volumes:
+      - ./data/minio:/data
+    ports:
+      - "127.0.0.1:9000:9000"
+      - "127.0.0.1:9001:9001"
+    networks:
+      - ppanel_net
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 10s
+      timeout: 5s
+      retries: 6
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  minio-init:
+    image: minio/mc:RELEASE.2025-07-21T05-28-08Z-cpuv1
+    container_name: ppanel-minio-init
+    restart: "no"
+    depends_on:
+      minio:
+        condition: service_healthy
+    environment:
+      MINIO_ROOT_USER: "${MINIO_ROOT_USER:?请在 .env 文件中设置 MINIO_ROOT_USER}"
+      MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:?请在 .env 文件中设置 MINIO_ROOT_PASSWORD}"
+      MINIO_BUCKET: "${MINIO_BUCKET:?请在 .env 文件中设置 MINIO_BUCKET}"
+    entrypoint:
+      - /bin/sh
+      - -c
+      - |
+        set -e
+        mc alias set local http://minio:9000 "$${MINIO_ROOT_USER}" "$${MINIO_ROOT_PASSWORD}"
+        mc mb --ignore-existing "local/$${MINIO_BUCKET}"
+    networks:
+      - ppanel_net
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
 volumes:
   loki_data:
   grafana_data:

ops/hifast-upload-chain-runbook-zh.md

@@ -0,0 +1,126 @@
+# HiFast 上传链路运维 Runbook
+
+## 适用范围
+
+本文档用于测试环境 `https://tapi.hifast.biz/v1/public/file/upload` 上传链路自检和 MinIO sidecar 运维。测试环境的对象存储应自包含在 compose 栈内，不依赖外部 `107.173.50.22:5017`。
+
+## 当前测试环境配置
+
+- Compose 文件：`/root/bindbox/docker-compose.cloud.yml`
+- 应用配置：`/root/bindbox/configs/ppanel.yaml`
+- MinIO 数据目录：`/root/bindbox/data/minio`
+- MinIO API：`http://127.0.0.1:9000`
+- MinIO Console：`http://127.0.0.1:9001`，仅绑定本机，需 SSH 隧道访问
+- Bucket：与 `ppanel.yaml` 的 `S3.Bucket` 保持一致，当前为 `hifastvpn`
+
+`ppanel-server` 使用 host 网络，所以 `S3.Endpoint` 必须写宿主机 loopback：
+
+```yaml
+S3:
+  Enable: true
+  Endpoint: "http://127.0.0.1:9000"
+  Bucket: "hifastvpn"
+  UsePathStyle: true
+```
+
+## 启停与状态检查
+
+```bash
+cd /root/bindbox
+docker compose -f docker-compose.cloud.yml up -d minio minio-init
+docker restart ppanel-server
+
+docker compose -f docker-compose.cloud.yml ps minio minio-init ppanel-server
+curl -fsS http://127.0.0.1:9000/minio/health/live
+curl -fsS https://tapi.hifast.biz/v1/common/heartbeat
+```
+
+`minio-init` 是一次性 bucket 初始化容器，正常状态是 `exited` 且退出码为 `0`：
+
+```bash
+docker inspect ppanel-minio-init --format 'status={{.State.Status}} exit={{.State.ExitCode}}'
+docker logs --tail 50 ppanel-minio-init
+```
+
+## Bucket 重建
+
+如 bucket 被误删或新环境首次初始化失败：
+
+```bash
+cd /root/bindbox
+docker compose -f docker-compose.cloud.yml up -d minio
+docker compose -f docker-compose.cloud.yml run --rm minio-init
+```
+
+确认 bucket：
+
+```bash
+docker logs --tail 50 ppanel-minio-init
+find /root/bindbox/data/minio -maxdepth 3 -type d | sort | head
+```
+
+## 上传链路自检
+
+基础健康检查：
+
+```bash
+curl -i https://tapi.hifast.biz/v1/common/heartbeat
+```
+
+完整上传需要有效用户 JWT。复测标准：
+
+- `POST /v1/public/file/upload` 返回 HTTP 200
+- 响应业务 `code=200`
+- `data.url` 指向 `S3.PublicBaseURL + object_key`
+- MinIO 数据目录可看到对应对象
+- `ppanel-server` 日志没有 `put object failed` 或 `context canceled`
+
+排查命令：
+
+```bash
+docker logs --since 10m ppanel-server | grep -Ei 'file/upload|put object|context canceled|s3'
+find /root/bindbox/data/minio/hifastvpn -type f | sort | tail
+```
+
+## 备份
+
+变更前必须备份：
+
+```bash
+cd /root/bindbox
+ts=$(date +%Y%m%d%H%M%S)
+cp docker-compose.cloud.yml docker-compose.cloud.yml.bak.hif-101.$ts
+cp .env .env.bak.hif-101.$ts
+cp configs/ppanel.yaml configs/ppanel.yaml.bak.$ts
+```
+
+MinIO 数据备份：
+
+```bash
+cd /root/bindbox
+tar -czf minio-data.$(date +%Y%m%d%H%M%S).tar.gz data/minio
+```
+
+## 回滚
+
+恢复外部 S3 配置或回到变更前状态：
+
+```bash
+cd /root/bindbox
+cp configs/ppanel.yaml.bak.YYYYMMDDHHMMSS configs/ppanel.yaml
+cp docker-compose.cloud.yml.bak.hif-101.YYYYMMDDHHMMSS docker-compose.cloud.yml
+cp .env.bak.hif-101.YYYYMMDDHHMMSS .env
+docker compose -f docker-compose.cloud.yml stop minio
+docker restart ppanel-server
+```
+
+保留 `/root/bindbox/data/minio` 便于复盘，不要在回滚时删除数据目录。
+
+## 旧 Endpoint 清理
+
+测试栈活动配置不得继续引用旧外部 endpoint：
+
+```bash
+cd /root/bindbox
+grep -R '107\.173\.50\.22:5017' -n docker-compose.cloud.yml configs/ppanel.yaml .env || true
+```