按"现象 → 可能原因 → 验证方法 → 处理"组织。所有命令默认在仓库根目录执行。
真实发生过的两个故障(含完整分析)记录在 incidents/:
docker compose ps:是不是有容器在Restarting/unhealthy;docker compose logs --tail 100 <service>:看错误;- 拿到响应的
X-Request-Id,在日志里 grep 同一个 ID,串起整条链路; - 看指标:
/metrics或 Prometheus,确认是错误率、延迟还是依赖故障; - 只有前三步都指向同一处时再改代码。
原因:服务配置没有读到 Etcd.Hosts,或 etcd 没起来。
docker compose ps etcd
docker compose exec etcd etcdctl endpoint health
docker compose exec storage-api sh -c 'cat /app/etc/config.yaml | head -30'注意 conf.MustLoad 会对配置做 ${VAR} 展开:
如果环境变量没注入,展开结果为空字符串,yaml 解析会丢掉整个字段或报类型错误。
典型表现:
error: config file ..., type mismatch for field "Minio.UseSSL"
说明 MINIO_USE_SSL 没有传进容器。检查 docker compose config 里该服务的 environment。
Docker Desktop 下容器内 etcd 的 --advertise-client-urls 是 etcd:2379,
宿主机进程拿到这个地址后无法解析。要么全部跑容器,要么像本地开发那样起一个
对外广播 127.0.0.1 的 etcd:
docker run -d --name cd-etcd-host -p 12379:2379 quay.io/coreos/etcd:v3.5.21 \
/usr/local/bin/etcd --name=etcd0 --data-dir=/etcd-data \
--listen-client-urls=http://0.0.0.0:2379 --advertise-client-urls=http://127.0.0.1:12379 \
--listen-peer-urls=http://0.0.0.0:2380 --initial-advertise-peer-urls=http://127.0.0.1:2380 \
--initial-cluster=etcd0=http://127.0.0.1:2380 --initial-cluster-state=newdocker compose logs mysql | grep -i error
docker compose exec mysql mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e 'show databases;'如果 cloud-drive 库是空的:初始化脚本只在数据卷为空时执行一次。
需要重建:docker compose down -v && docker compose up -d(会清空数据)。
bind: address already in use:改 docker-compose.yml 的宿主机端口映射,或停掉占用进程。
Docker Desktop 的端口转发在部分机器上首次建立连接就要 1-2 秒。
表现是 context deadline exceeded 与 [SQL] slowcall,而容器内跑却没有这个问题。
处理方式(三选一):
- 全部跑容器(推荐,也是部署形态);
- 本地开发时把
Timeout调大(本仓库的service/*/etc/*.yaml已设成 10-60 秒); - DSN 加
interpolateParams=true减少一次 Prepare 往返(本仓库已加)。
不是故障,是配额不足。查看:
curl -s http://127.0.0.1:8000/v1/users/me/quota -H "Authorization: Bearer $TOKEN"如果 usedBytes 明显偏高但用户没有那么多文件,说明有账目漂移:
go run ./tools/reconcile -f service/storage/rpc/etc/storage.yaml| 返回信息 | 原因 |
|---|---|
request body is larger than the declared part size |
多发字节 |
failed to store part, body size does not match the declared size |
少发字节 |
part N size mismatch: got X want Y |
与服务端计算的期望长度不一致 |
part number N exceeds total chunks M |
分片号越界 |
分片长度必须严格等于:
part < totalChunks → chunkSize
part == totalChunks → size - (totalChunks-1)*chunkSize
有分片没传成功。查进度:
curl -s http://127.0.0.1:8001/v1/uploads/$UPLOAD_ID -H "Authorization: Bearer $TOKEN"missingParts 就是还缺的片,补传即可。
客户端算的 SHA-256 与服务端读到的内容不一致。常见原因:
- 客户端上传时分片顺序错乱;
- 客户端把压缩/编码后的内容算成了原文的 hash;
- 传输过程中内容被中间代理改写(极少见)。
服务端在检测到不一致时会删除已合并对象并把任务标记 failed。
正常情况下 15 分钟内会被后台任务放回 uploading。手动干预:
docker compose exec mysql mysql -uroot -p -e \
"update cloud-drive.upload_tasks set status='uploading' where upload_id='<id>';"先看是不是缓存问题:
docker compose exec redis redis-cli -n 0 KEYS 'cache:users:*'
docker compose exec redis redis-cli -n 0 FLUSHALL # 仅开发环境如果 flush 之后能登录,说明缓存里残留了"用户不存在"的占位符。 根因是绕过 model 的写操作没有失效缓存——完整分析见 incidents/001。
规则:任何直接用 session.ExecCtx / ExecNoCacheCtx 写库的地方,
都必须显式调用对应的 Invalidate / DelCacheCtx。
看 panic 的调用栈指向哪个 l.svcCtx.Xxx:
docker compose logs --tail 200 user.rpc | grep -A5 'nil pointer'ServiceContext 里某个依赖没有在 NewServiceContext 中赋值。
完整案例见 incidents/002。
触发限流(默认每 IP 5 rps,突发 10)。生产环境调 deploy/config/user-api.yaml 的
Limit.RPS / Limit.Burst,或换用基于 Redis 的全局限流。
可能原因:
- 文件状态不是
available(上传没完成); storage_objects.status != 'available';- 对象在 MinIO 里真的没了。
docker compose exec mysql mysql -uroot -p -e \
"select id,status,object_key from cloud-drive.files where id=<fileId>;"
docker compose exec mysql mysql -uroot -p -e \
"select object_key,status,size,gc_attempts,last_error from cloud-drive.storage_objects where object_key='<key>';"确认对象是否存在:MinIO 控制台 http://127.0.0.1:19001 或
go run ./tools/reconcile -f service/storage/rpc/etc/storage.yaml- 检查
storage-api是否Restarting; - 检查
/readyz:返回 503 通常是 bucket 不存在或 MinIO 不可用;curl -s http://127.0.0.1:8002/readyz
- 大文件下载时 file-api 的内存应该保持平稳(流式转发)。若内存上涨,
说明有人把
io.CopyBuffer改成了io.ReadAll——不要这么改。
Range 越界或语法错误(多段 Range 不支持)。响应里带 Content-Range: bytes */<size>。
| 现象 | 原因 |
|---|---|
granted=false, reason=share was revoked |
已被撤销 |
share has expired |
过了 expires_at |
share access limit reached |
达到 maxAccessCount |
invalid share password |
密码错误(bcrypt 比对失败) |
file is not available |
文件被删或未完成上传 |
分享下载 403 时先调 POST /v1/shares/{token}/access 看具体 reason。
select object_key, gc_attempts, last_error from storage_objects where status='deleting';后台任务每 10 分钟重试一次。持续失败时检查:
- MinIO 是否可用、bucket 是否存在;
- MinIO 用户是否有 delete 权限;
- 指标
clouddrive_storage_object_gc_failures_total与clouddrive_storage_object_gc_backlog是否在上涨(Prometheus 告警会报)。
用 MinIO 控制台看 parts/ 前缀。48 小时前的孤儿分片会被自动清理。
要立即清理:删除对应 upload_tasks 行后重启 storage.rpc(不建议手工操作生产数据)。
| 现象 | 先看什么 |
|---|---|
| 接口整体变慢 | http_server_requests_duration_ms 的 P95 按 path 拆分 |
| 只有 RPC 慢 | rpc_server_requests_duration_ms 按 method 拆分 |
| MySQL 慢 | show processlist、慢查询日志;列表查询是最重的 |
| 上传慢 | 单分片耗时 vs MinIO 写入耗时;先直连 MinIO 测一次 |
| 下载慢 | 对比直连 storage-api 与经 file-api 的吞吐 |
# RPC:在 service/<svc>/rpc 目录下
goctl rpc protoc <svc>.proto --go_out=./types --go-grpc_out=./types \
--zrpc_out=. --module=cloud-drive/service/<svc>/rpc --client=true
# API:在 service/<svc>/api 目录下
goctl api go --api <svc>.api --dir .
# model:从 DDL 生成
goctl model mysql ddl -src service/<svc>/model/<svc>.sql -dir <临时目录> -c
# 只把 *_gen.go 拷回 service/<svc>/model/,保留手写的 *model.go注意:
- goctl 不会覆盖已存在的 logic 文件,但会覆盖
handler/、types/、routes.go; routes.go里有手工维护的中间件段落,重新生成后需要补回;- 生成模型的
package名取决于输出目录名,拷回前要改成package model; - 新增/修改任何绕过 model 的写库逻辑时,务必显式失效相关缓存(见 3.1)。
docker compose down -v
docker compose up -d --build
go run ./scripts/e2e这会清空 MySQL、Redis、etcd、MinIO 的全部数据。只在开发环境这么做。