From 2ae9ad40deba04e762361cffd3545beb06c50561 Mon Sep 17 00:00:00 2001 From: shanshanzhong Date: Wed, 27 May 2026 20:04:14 -0700 Subject: [PATCH] =?UTF-8?q?=E8=BF=90=E7=BB=B4(#101):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E7=8E=AF=E5=A2=83=20MinIO=20=E4=B8=8A?= =?UTF-8?q?=E4=BC=A0=E9=93=BE=E8=B7=AF=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: multica-agent --- .env.example | 6 ++ docker-compose.cloud.yml | 59 ++++++++++++ ops/hifast-upload-chain-runbook-zh.md | 126 ++++++++++++++++++++++++++ 3 files changed, 191 insertions(+) create mode 100644 ops/hifast-upload-chain-runbook-zh.md diff --git a/.env.example b/.env.example index 6951e3f..dcb85de 100644 --- a/.env.example +++ b/.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 diff --git a/docker-compose.cloud.yml b/docker-compose.cloud.yml index de93cc1..2705524 100644 --- a/docker-compose.cloud.yml +++ b/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: diff --git a/ops/hifast-upload-chain-runbook-zh.md b/ops/hifast-upload-chain-runbook-zh.md new file mode 100644 index 0000000..4aa883b --- /dev/null +++ b/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 +```