Files

T

shanshanzhong147 18c667bf21 文档(#99 ): 补充上传链路自检 runbook

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

2026-05-27 19:43:07 -07:00

4.1 KiB

Raw Blame History

Hifast 上传链路自检 Runbook

本文档用于排查 POST /v1/public/file/upload、/upload/init、/upload/complete 相关问题。上传链路依赖：

客户端 -> Nginx -> ppanel-server -> S3/RustFS endpoint

1. 先确认业务服务健康

在测试机执行：

curl -k -sS -m 8 -i https://tapi.hifast.biz/v1/common/heartbeat | head -30
docker ps --format '{{.Names}} {{.Image}} {{.Status}} {{.Ports}}'
ss -lntp | grep -E ':(80|443|8080|3306|6379)'

预期：

/v1/common/heartbeat 返回 HTTP 200，业务 code=200
ppanel-server、ppanel-mysql、ppanel-redis 运行中
Nginx 监听 80/443，ppanel 监听 8080

2. 检查上传配置

测试环境当前业务容器使用挂载配置：

docker inspect ppanel-server --format '{{json .Mounts}}'
docker cp ppanel-server:/app/etc/ppanel.yaml /tmp/ppanel.yaml
awk '/^S3:/{flag=1} flag && /^[A-Za-z0-9_]+:/{if($1!="S3:") exit} flag{print}' /tmp/ppanel.yaml \
  | sed -E 's/(AccessKey:).*/\1 ***REDACTED***/; s/(SecretKey:).*/\1 ***REDACTED***/; s/(SessionToken:).*/\1 ***REDACTED***/'

重点确认：

S3.Enable: true
S3.Endpoint 是 ppanel-server 所在机器可以访问的地址
S3.Bucket 存在且凭据有 PutObject / HeadObject 权限
S3.UsePathStyle 与对象存储实现一致
S3.PublicBaseURL 只影响返回 URL，不代表写入 endpoint

3. 检查对象存储连通性

先从测试机主机网络检查：

endpoint='http://107.173.50.22:5017'
host='107.173.50.22'
port='5017'

timeout 5 bash -lc "</dev/tcp/${host}/${port}" && echo tcp_ok || echo tcp_fail
curl -v --connect-timeout 5 --max-time 10 -I "${endpoint}/"
curl -v --connect-timeout 5 --max-time 10 -I "${endpoint}/hifastvpn"
ip route get "${host}"

判定：

TCP 超时：优先查对象存储主机防火墙、安全组、服务监听、源 IP 白名单
TCP 通但 HTTP 空响应：优先查 endpoint 协议、反向代理、对象存储进程健康
返回 S3 XML/鉴权错误：网络已通，再查 AK/SK、bucket、path-style 配置

4. 检查应用日志

docker logs --since 3h ppanel-server 2>&1 \
  | grep -Ei 'put object failed|upload|s3|timeout|context canceled|error' \
  | tail -120

典型根因：

put object failed ... context canceled 且请求耗时约 60 秒：上游对象存储请求没有在 Nginx upstream timeout 前完成，通常是 S3.Endpoint 不可达或对象存储服务 hang。
立即返回业务错误：通常是 S3.Enable=false、Content-Type 不在白名单、bucket/权限错误。

5. Nginx 检查

grep -RIn 'proxy_pass\|proxy_read_timeout\|client_max_body_size\|tapi.hifast.biz' /etc/nginx/sites-enabled /etc/nginx/conf.d
nginx -t

注意：单纯放大 proxy_read_timeout 只能掩盖现象，不能修复对象存储不可达。

6. 修复与回滚

修复优先级：

恢复对象存储 endpoint 的网络访问或服务监听。
如 endpoint 已迁移，更新 /root/bindbox/configs/ppanel.yaml 的 S3.Endpoint，重启 ppanel-server。
如果凭据或 bucket 变更，同步更新 S3.AccessKey、S3.SecretKey、S3.Bucket、S3.UsePathStyle。

改配置前先备份：

cp /root/bindbox/configs/ppanel.yaml /root/bindbox/configs/ppanel.yaml.bak.$(date +%Y%m%d%H%M%S)
docker restart ppanel-server

回滚：

cp /root/bindbox/configs/ppanel.yaml.bak.YYYYMMDDHHMMSS /root/bindbox/configs/ppanel.yaml
docker restart ppanel-server
curl -k -sS -m 8 -i https://tapi.hifast.biz/v1/common/heartbeat | head -30

7. 验证

使用有效 JWT 和有效签名复测：

curl -i -X POST 'https://tapi.hifast.biz/v1/public/file/upload' \
  -H 'x-app-id: android-client' \
  -H 'Authorization: <client-jwt>' \
  -H 'x-signature-version: v101' \
  -H 'login-type: device' \
  -H 'x-signature: <sig>' \
  -H 'x-nonce: <nonce>' \
  -H 'x-timestamp: <ts>' \
  -F 'biz_type=app-package' \
  -F 'file=@nconf.zip;type=application/zip' \
  --max-time 120

预期：

HTTP 不再出现 504 Gateway Time-out
业务响应 code=200
docker logs ppanel-server 不再出现新的 put object failed

4.1 KiB Raw Blame History Unescape Escape