131 lines
4.1 KiB
Markdown
131 lines
4.1 KiB
Markdown
# Hifast 上传链路自检 Runbook
|
||
|
||
本文档用于排查 `POST /v1/public/file/upload`、`/upload/init`、`/upload/complete` 相关问题。上传链路依赖：
|
||
|
||
`客户端 -> Nginx -> ppanel-server -> S3/RustFS endpoint`
|
||
|
||
## 1. 先确认业务服务健康
|
||
|
||
在测试机执行：
|
||
|
||
```bash
|
||
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. 检查上传配置
|
||
|
||
测试环境当前业务容器使用挂载配置：
|
||
|
||
```bash
|
||
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. 检查对象存储连通性
|
||
|
||
先从测试机主机网络检查：
|
||
|
||
```bash
|
||
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. 检查应用日志
|
||
|
||
```bash
|
||
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 检查
|
||
|
||
```bash
|
||
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. 修复与回滚
|
||
|
||
修复优先级：
|
||
|
||
1. 恢复对象存储 endpoint 的网络访问或服务监听。
|
||
2. 如 endpoint 已迁移，更新 `/root/bindbox/configs/ppanel.yaml` 的 `S3.Endpoint`，重启 `ppanel-server`。
|
||
3. 如果凭据或 bucket 变更，同步更新 `S3.AccessKey`、`S3.SecretKey`、`S3.Bucket`、`S3.UsePathStyle`。
|
||
|
||
改配置前先备份：
|
||
|
||
```bash
|
||
cp /root/bindbox/configs/ppanel.yaml /root/bindbox/configs/ppanel.yaml.bak.$(date +%Y%m%d%H%M%S)
|
||
docker restart ppanel-server
|
||
```
|
||
|
||
回滚：
|
||
|
||
```bash
|
||
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 和有效签名复测：
|
||
|
||
```bash
|
||
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`
|