1.17.0 The Skill function module is unable to upload the “skill.zip” package.

快速结论：该报错通常出现在 Dify 1.17.0 自托管环境的 Skill 功能模块中，优先检查 Docker 容器是否已执行数据库迁移（flask db upgrade），并确认 ENABLE_SKILL 环境变量未被设为 false。

适用环境：Dify 1.17.0，Docker 自托管（Self Hosted）部署方式。

最快修复方案：暂无确认的一步修复方案。可优先尝试在 API 容器中执行 docker compose exec api flask db upgrade，并检查 .env 文件中的 ENABLE_SKILL 配置项。

注意事项：上述方案仅为可能原因的排查建议，Issue 中尚未确认具体修复步骤；上传失败可能需要结合具体的 HTTP 状态码（400/500）进一步定位是校验错误、迁移缺失还是代理问题。

问题场景

用户在 Dify 1.17.0 的 Skill 功能模块中尝试上传 skill.zip 包时，上传操作无法完成。该功能为 1.17.0 版本新增（对应 PR #39675），因此此问题多见于升级或初次部署该版本的用户。

报错原文

1.17.0 The Skill function module is unable to upload the "skill.zip" package.

原因分析

根据 Issue 讨论，可能原因包括：

数据库迁移未执行：Skill 功能新增了数据库迁移脚本（2026_08_24_1052-a4f8d2c9e1b0_add_workspace_skill_management），如果容器启动时未执行迁移，相关数据表不存在会导致上传失败。
ENABLE_SKILL 配置被禁用：后端存在该功能开关（默认 true），若 .env 中设为 false 则无法使用。
ZIP 包结构不符合要求：必须为 .zip 或 .skill 文件且包含带 YAML frontmatter（含 name、description 字段）的 SKILL.md，name 需匹配 ^[a-z0-9]+(?:-[a-z0-9]+)*$ 格式；多技能包或缺 SKILL.md 会返回 400 错误。
Squid 代理拦截：INTERNAL_FILES_URL 或 FILES_URL 配置不当（尤其解析到内网 IP 时）可能导致代理拦截上传请求。

环境排查

确认 Dify 版本为 1.17.0。
检查数据库迁移是否已执行。
检查 .env 中的 ENABLE_SKILL 是否保持默认 true。
核实 INTERNAL_FILES_URL、FILES_URL 配置是否正确。
确认 Docker 镜像是否已更新至包含 #39733 修复的最新版本。

解决步骤

在 API 容器中执行数据库迁移：docker compose exec api flask db upgrade。
检查 .env 文件，确保未设置 ENABLE_SKILL=false。
验证 skill.zip 包格式：确认内含 SKILL.md，且头部 YAML frontmatter 中 name 与 description 字段存在；name 需符合小写字母/数字加连字符的命名规则，如 my-skill-1。
如果使用代理环境，检查 INTERNAL_FILES_URL 与 FILES_URL 是否解析到公网可访问地址，避免被 Squid 代理拦截。
如仍未解决，升级 Docker 镜像至包含 Squid 代理修复（#39733）的最新版本。

验证方法

完成上述排查步骤后，重新在 Skill 功能模块中上传 skill.zip 包。若上传成功并出现技能列表，说明问题已解决。若仍失败，建议抓取浏览器开发者工具中的 Network 请求，获取具体的 HTTP 状态码与响应内容，以便进一步判断属于 400 参数校验错误、500 数据库异常还是代理拦截问题。