Skip to content

常见问题

组件使用中常见问题的排查与恢复。开始排查前先打开 debug 日志：

s deploy --debug
s cli fc-sandbox team list --debug --region cn-hangzhou -a default

debug 日志包含每个 API 的请求参数与响应体（apiKeyValue 已脱敏为 ***），足以定位绝大多数问题。

错误码对照

错误码 / 状态码 含义 处理
TeamNotFound / VolumeNotFound / ApiKeyNotFound / QuotaNotFound / ResourceNotFound / 404 资源不存在 组件内部按"不存在"处理：deploy 走创建，remove 跳过
TeamAlreadyExists / VolumeAlreadyExists / ApiKeyAlreadyExists / 409 同名资源已存在 通常是并发部署，或名字被同账号其他 Team 占用，见改名之后线上多了一份
AccessDenied / 403 权限不足 检查 access 的 RAM 策略，见权限不足（403）
InvalidArgument / 400 参数不合法 看 debug 日志里的请求体，多为 expireTime 格式或 ipAddress 网段写法问题

除"资源不存在"外的错误码，组件不做分支判断也不转译，一律原样抛给 s 打印 —— 服务端的 Code / Message / RequestId 是排查的关键线索。

地域相关的 warn

Invalid region, The allowed regions are cn-hangzhou,cn-shanghai,cn-beijing,cn-shenzhen,cn-hongkong,ap-southeast-1,us-west-1,us-east-1

这是 warn 而不是错误。组件不为每个地域预置接入点，endpoint 按 fcsandbox.<region>.aliyuncs.com 推导，所以地域一旦开服就能直接用，新地域上线无需升级组件。

因此这条 warn 有两种可能：

  1. 地域已开服，只是组件的列表还没跟上 —— 请求会正常成功，警告可以忽略（欢迎提 issue 补列表）；
  2. 地域尚未开服 —— 后续 API 调用会失败。请先用列表内的地域验证，或用 endpoint 显式指定接入点。

取值参见支持的地域。

完全不填 region 则直接报错：

Region not specified, please specify --region

权限不足（403）

最小复现命令是 team list：

s cli fc-sandbox team list --region cn-hangzhou -a default --debug

若它也 403，问题在 access 的凭证或 RAM 策略上，与组件无关，按顺序排查：

  1. s config get -a default 确认 AK 正确；
  2. 确认该 RAM 用户 / 角色有函数计算相关权限（写操作 AliyunFCFullAccess，只读操作 AliyunFCReadOnlyAccess）；
  3. 子账号还需确认目标资源组（resourceGroupID）有权访问。

Team 找不到

Team "dev" not found in region cn-hangzhou

三种可能，按顺序排查：

  1. 地域不对 —— Team 是地域级资源，--region 与创建时不一致就找不到。用 s cli fc-sandbox team list --table 逐地域确认。
  2. 名字不对 —— 服务端的 name 过滤是模糊语义，组件在客户端做精确匹配，大小写和空格都算差异。
  3. 改过名 —— 见下一节。

另外，deploy 时若 volume / apiKey 的部署先于 Team 存在，会看到：

Team "dev" not found in region cn-hangzhou, deploy the team first

此时先执行 s deploy --team，再部署内嵌资源，或直接 s deploy 让组件按 team → volumes → apiKeys 的固定顺序编排。

改名之后线上多了一份

teamName / volumeName / apiKeyName 都是身份键。改名后组件按新名字查不到线上资源，会新建一个，旧的留在线上不动，也不会被回收。

s cli fc-sandbox team list --table --region cn-hangzhou -a default   # 确认旧资源
s cli fc-sandbox team remove --team-name <旧名字> --region cn-hangzhou -a default -y

想保留资源只改名，走 CLI 的 --new-team-name（需要服务端 allowUpdateTeamName 为 true），再同步修改 s.yaml 的 props.teamName：

s cli fc-sandbox team update --team-name dev --new-team-name prod --region cn-hangzhou -a default

Volume 和 ApiKey 没有改名能力（ApiKey 的 --new-api-key-name 只改名不动值，Volume 完全不支持），Volume 改名只能 remove + 重建。

改了 volume 的 bucket 但线上没变

Volume "data" config differs from the remote one, but the OSS / AgenticFS config is IMMUTABLE after creation — only the status change is sent.

这是预期行为，不是 bug。服务端 UpdateVolume 只接受 status。要应用配置变更只能重建：

s cli fc-sandbox volume remove --volume-name data --team-name dev --region cn-hangzhou -a default -y
s deploy --volume data

⚠️ remove volume 会丢失挂载关系，重建前确认没有沙箱正在使用它。详见 Volume 存储配置创建后不可修改。

apiKey 的值丢了

不需要重置 —— DescribeApiKey 会返回明文，直接取回即可：

s cli fc-sandbox apikey get --team-name dev --api-key-name ci --region cn-hangzhou -a default

⚠️ 这条命令的输出含密钥明文，不要接进 CI 日志或在共享终端里执行。apikey list / s info 只给 apiKeyMask，那是 ListApiKeys 接口本身的行为，不是组件遮的。详见约束二。

只有需要轮换凭证（怀疑泄露、定期更换）时才用 reset：

s cli fc-sandbox apikey reset --team-name dev --api-key-name ci --region cn-hangzhou -a default

⚠️ 重置会立即失效旧值，先确认所有使用方都能同步更新。

sync 产物里没有 apiKey 的值

设计如此 —— s.yaml 会进代码仓库，凭证不能落盘。sync 用字段白名单生成 yaml，apiKeyValue 与 apiKeyMask 都不在白名单里，同步完会 warn 并指向取值的命令：

The api key values are NOT synced — a credential must not be written into s.yaml.
  Read one when you need it: s cli fc-sandbox apikey get --api-key-name <name> --team-name <team>

同步来的 s.yaml 可以直接 s deploy（apiKey 已存在则走 update，不会重置值）。

deploy 提示线上有未声明的资源

Volumes exist online but are not declared in s.yaml: xxx. Deploy never removes them — use "s cli fc-sandbox volume remove" if they are obsolete.

只是提示。deploy 永不删除 s.yaml 里没声明的资源。确认要删就显式执行：

s cli fc-sandbox volume remove --volume-name xxx --team-name dev --region cn-hangzhou -a default -y

Not found in s.yaml: ghost

--team / --volume / --api-key 只能指定 s.yaml 里声明过的名字 —— 这是防止误操作线上资源的护栏。s remove 的报错会带上具体是哪一类，例如：

Not found in s.yaml volumes: ghost

要操作未声明的资源，请走 CLI 子命令（team / volume / apikey）。

部署卡在交互确认

CI 环境加 -y：

s deploy -y
s remove -y

-y 会跳过所有确认，包括删除确认，请谨慎在生产环境使用。

完全清理一个 Team

s remove -y     # 按 s.yaml 逆序删 apiKeys → volumes → team

或不依赖 s.yaml：

s cli fc-sandbox apikey list   --team-name dev --table --region cn-hangzhou -a default
s cli fc-sandbox apikey remove --team-name dev --api-key-name <name> --region cn-hangzhou -a default -y
s cli fc-sandbox volume list   --team-name dev --table --region cn-hangzhou -a default
s cli fc-sandbox volume remove --team-name dev --volume-name <name> --region cn-hangzhou -a default -y
s cli fc-sandbox team remove   --team-name dev --region cn-hangzhou -a default -y

必须按这个顺序 —— Team 上还挂着 volume / apiKey 时删除会失败。

从线上重建 s.yaml

s sync --target-dir /tmp/recovered --team-name dev --region cn-hangzhou
# 产物：/tmp/recovered/cn-hangzhou_dev.yaml
# 不传 --target-dir 时落在 <s.yaml 所在目录>/sync-clone/cn-hangzhou_dev.yaml

详见 sync 命令。

配额不足

s cli fc-sandbox quota get --tag-value default --region cn-hangzhou -a default
s cli fc-sandbox quota put --tag-value default --cpu-cores 32 --memory-gb 64 --region cn-hangzhou -a default

配额是账号 / tag 级别，与 Team 无关，也不在 s.yaml 里，只能通过 quota 命令 管理。

上报问题时请附上

  1. s -v 与组件版本；
  2. 脱敏后的 s.yaml；
  3. --debug 完整输出（apiKeyValue 已自动脱敏，但请自行检查 AK 与 bucket 等信息）；
  4. 地域与请求 ID（debug 日志里的 RequestId）。