制品库操作示例

本文档说明应用开发完成后，如何在制品库中完成从添加制品、配置版本到提交发布的基础流程。适用于已经准备好后端镜像、后端包、传统站点代码包、前端包、Helm 包或额外 YAML 的应用。

制品库入口：

https://idc.w7.com/appgroup/w7-zpkv2-root/micro?appmicro=%7Bfrontend%7D%23%2Fzpk

操作前准备

开始前先准备以下信息：

项目	说明
制品标识	使用 w7-test 这类格式；w7- 后面的业务标识只能使用字母或数字，不能包含 - 或 _
制品名称	展示给用户的应用名称
分类	按应用场景选择后台应用、系统组件等分类
代码包	后端包、传统站点代码包、前端包、Helm 包或额外 YAML，按应用形态提供；有面板页面时通常需要前端包
入口信息	面板菜单名称、访问路径、控制台入口、是否支持 iframe
运行配置	应用端口、环境变量、启动参数、网关域名转发规则
依赖关系	当前制品安装前需要依赖的其他制品
版本说明	当前版本的变更内容、安装说明和注意事项

推荐先按应用形态整理交付物：

应用形态	必备交付物	常见补充项
纯后端应用	后端代码包或镜像配置	启动参数、环境变量、网关域名转发、安装依赖
后端 + 前端应用	后端代码包、前端代码包、控制台入口	菜单配置、角色权限、网关域名转发、安装依赖
K8sYaml 应用	Helm 包或额外 YAML	values、网关域名转发、安装说明

上传前先确认代码包可以独立追溯到 Git tag、commit 或构建流水线记录。正式发布不要使用临时包、覆盖型镜像 tag 或本地调试配置。

添加制品

进入制品库后点击“添加制品”，填写制品标识、名称、分类等基础信息。

标识需要保持稳定，后续版本、包配置和发布记录都会围绕这个标识维护。以 w7-docs 为例，完整标识由 w7- 前缀和业务标识组成，其中业务标识部分为 docs，不能再包含横线或下划线。

填写时按以下规则确认：

字段	填写要求
标识	一旦创建后不要随意变更；推荐用应用英文名或模块英文名
名称	使用用户能理解的应用名称，不要只写内部代号
分类	决定应用在制品库和应用市场中的归类，按实际使用场景选择
描述	简要说明应用解决的问题，避免只写版本号或技术栈

标识示例：

示例	是否推荐	说明
w7-docs	推荐	后缀 docs 只包含字母
w7-test1	推荐	后缀 test1 包含字母和数字
w7-docs-api	不推荐	后缀部分包含额外的 -
w7-docs_api	不推荐	后缀部分包含 _

进入版本管理

制品创建完成后进入详情页。详情页通常包含“版本管理、付费设置、应用介绍、发布设置”等页签。

在版本管理中确认基础信息、当前线上版本和开发版本。如果是首次发布，先创建开发版本；如果是已有制品升级，基于当前开发版本继续配置或新建版本。

版本管理页建议按下面的顺序处理：

1. 确认基础信息是否和刚创建的制品一致。
2. 检查当前线上版本，避免把测试版本误发布到线上。
3. 创建或选择开发版本，后续配置都先落到开发版本。
4. 进入后端包管理，先选择代码配置类型，再按类型补齐对应配置。
5. 原生应用继续配置应用配置、启动参数、网关域名转发和安装依赖；传统应用和 K8sYaml 不需要进行原生应用配置。
6. 如果制品包含子应用，继续添加子应用并按主应用相同方式配置。

版本号应保持可读、可追溯。推荐使用 v1.0.0、v1.0.1 这类语义化版本；测试阶段可以使用 v1.0.0-beta.1，但正式发布前要确认用户侧能识别该版本含义。

配置后端包管理

在版本管理页进入“后端包管理”。后端包管理先选择代码配置类型，再按类型填写配置。这里配置的是后端应用运行和访问规则，不是前端管理端入口。

上传并配置后端包只表示应用具备后端服务能力。制品可以只有后端、没有前端包；这种情况下不会在面板展示对应的前端菜单入口。需要出现在面板菜单中的应用，必须继续补齐管理端、前端包和菜单配置。

选择代码配置类型

代码配置类型决定后续需要填写的内容：

类型	配置方式	说明
原生应用	需要配置原生应用配置，并按需配置通用设置	适合以容器应用方式运行的后端服务
传统应用	不需要进行原生应用配置	最后会安装到站点管理中；代码包是传统站点代码包
K8sYaml	不需要进行原生应用配置	支持上传 Helm 包和额外 YAML

只有选择“原生应用”时，才需要继续填写下面的应用配置。选择“传统应用”或“K8sYaml”时，不需要配置镜像、存储、挂载、端口、环境变量和运行命令这类原生应用字段。

代码配置类型确认后，再按实际需要配置启动参数、网关域名转发、安装依赖和子应用。

原生应用配置

先根据应用运行方式选择应用类型：

应用类型	适用场景
无状态应用	不需要持久化本地状态，适合大多数 API 服务、后台任务入口
有状态应用	需要稳定存储或实例身份，适合数据库、队列、带本地状态的服务
守护进程应用	需要在节点上长期运行，适合节点级采集、代理、巡检类服务

原生应用的应用配置字段较多，日常发布制品时优先确认以下常用项即可：

配置项	使用说明
应用镜像	填写应用运行镜像，例如 nginx:latest 或制品构建后的业务镜像；镜像仓库、拉取策略按实际镜像来源配置
CPU/内存限制	按服务资源需求填写；不确定时先使用保守值，避免安装后占用过高
数据卷	应用需要持久化文件、缓存或配置时添加；纯无状态服务可以不配置
挂载点	将数据卷挂载到容器内目标路径；注意路径不要覆盖镜像内必要目录
环境变量	填写运行参数、开关和非敏感默认值；支持批量编辑 key=value
暴露端口	填写容器对外提供服务的端口和协议，例如 HTTP 服务常见为 80 或 8000
运行命令	需要覆盖镜像默认启动命令时填写；不需要覆盖时保持空

高级设置中常用的是挂载点、环境变量、暴露端口和运行命令。端口只声明容器服务端口，不等同于外部访问入口；后端请求如何转发，需要在网关域名转发设置中单独配置。

常用项填写建议：

配置项	使用说明
镜像	使用当前版本对应的正式构建产物，避免引用开发机临时镜像
存储	只有应用确实需要持久化时添加数据卷；否则保持无状态更容易升级和扩缩容
挂载	目标路径要和应用代码读取路径一致，例如 /data、/app/config
端口	和应用实际监听端口一致；后续网关域名转发设置会基于该端口做请求转发
环境变量	只放运行必需项；密码、密钥等敏感值不要写成公开默认值
命令	仅在镜像默认 ENTRYPOINT 或 CMD 不满足时填写

传统应用配置

选择“传统应用”后，不需要进行原生应用配置。传统应用最后会安装到站点管理中。

传统应用里的代码包是传统站点代码包。配置时需要选择站点运行环境类型和环境版本，例如 Python、Node.js、Go、PHP 以及对应版本。CMD 用于填写站点启动或运行命令。

传统应用常用配置：

配置项	说明
环境类型	选择站点运行环境，例如 Python、Node.js、Go、PHP
环境版本	选择对应运行时版本
代码包	上传传统站点代码包
CMD	填写站点启动或运行命令

K8sYaml 配置

选择“K8sYaml”后，不需要进行原生应用配置。K8sYaml 类型面向已经准备好 Kubernetes 部署描述的应用，支持上传 Helm 包和额外 YAML。

K8sYaml 常用配置：

配置项	说明
启用 Helm 配置	需要通过 Helm Chart 安装时开启；只使用额外 YAML 时可不启用
Chart 包来源	支持选择 Helm 仓库或 Helm 下载包
Chart 包地址	选择 Helm 下载包时填写或上传 Chart 包地址
安装配置	通过键值方式补充 Helm values 覆盖项
YAML 配置	上传或填写额外 YAML，支持添加多个 YAML 配置
标题	为额外 YAML 添加可识别名称
YAML	填写具体 YAML 内容

K8sYaml 适合已经有标准部署描述的应用。发布前应确认 Helm 包、安装配置和额外 YAML 对应同一个版本，避免 Chart 和 YAML 引用的镜像或参数不一致。

通用设置

完成代码配置类型对应的内容后，再按应用需要配置启动参数、网关域名转发、安装依赖和子应用。不是所有制品都需要这些配置；纯静态或纯后端内部能力可以只保留必要项。

启动参数设置

启动参数用于把安装时需要用户决定的值暴露出来，例如服务端口、数据目录、功能开关、初始化账号或外部服务地址。参数应尽量使用清晰的名称和默认值，让安装者不需要理解底层部署细节也能完成配置。

启动参数建议：

项目	说明
参数名称	使用业务可理解的名称，不要只写内部变量名
默认值	能安全运行的默认值可以提供；敏感信息不要提供公开默认值
必填项	没有默认值且应用启动必需的参数应标记为必填
说明文案	写清楚参数用途、格式和影响范围

网关域名转发设置

网关域名转发设置用于配置后端请求入口和转发规则。需要让前端或外部入口访问后端服务时，在这里声明域名、路径、转发目标和匹配规则。

注意：制品页不会直接展示或维护 Service、Ingress 等底层资源明细。开发者只需要按制品库提供的网关域名转发设置填写访问规则。

常见配置：

配置项	说明
域名	需要通过域名访问后端服务时填写
请求路径	前端或外部访问使用的路径
转发目标	指向后端应用的服务端口
匹配规则	按路径、前缀或页面提供的规则转发

安装依赖

安装依赖用于声明当前制品依赖的其他制品。比如当前应用需要数据库、缓存、消息队列或某个基础组件先安装完成，就应该在安装依赖中声明。

依赖配置建议：

项目	说明
依赖制品	选择当前应用运行前必须存在的制品
版本要求	有兼容性要求时写清楚最低版本或推荐版本
必需/可选	核心运行依赖标记为必需；增强能力可以标记为可选
安装顺序	有顺序要求时在说明中写清楚

子应用

制品可以添加子应用。子应用适合一个制品内包含多个后端服务的场景，例如主 API 服务、任务服务、回调服务或独立 worker。

子应用的配置方式和主应用一样，也需要先选择代码配置类型：原生应用配置应用配置、启动参数设置、网关域名转发设置和安装依赖；传统应用配置环境类型、环境版本、代码包和 CMD；K8sYaml 上传 Helm 包和额外 YAML。子应用是否需要前端菜单，仍然取决于是否配置管理端、前端包和菜单入口。

配置代码包和变量传递

如果应用包含前端入口，需要上传前端代码包，并配置控制台入口、可访问角色、iframe 支持和接口地址。纯后端制品不需要上传前端包，也不会生成面板菜单入口。

请求头和 Query 参数用于把面板侧上下文传递给应用前端或后端。只传递应用运行必需的信息，避免把无关凭据或调试参数写入正式版本。

前端包配置建议：

配置项	说明
上传代码包	上传构建后的前端产物压缩包；压缩包根目录应能找到入口文件
控制台入口	面板打开应用时访问的前端路径，需和前端路由配置一致
角色	控制哪些角色可以访问该入口，默认不要给无关角色开放
支持 iframe	应用需要被嵌入面板时开启；如果应用主动跳转顶层窗口，需要先适配
接口地址	前端调用应用自身 API 的地址；后端转发关系以网关域名转发设置为准
请求头	传递 token、租户、命名空间等必要上下文
Query	传递轻量参数，避免放敏感信息

变量传递要保持最小化。比如前端只需要面板 API 地址和应用 token，就不要额外传递完整用户信息、调试开关或集群凭据。

提交并发布

配置完成后检查菜单配置。需要面板内入口时，添加一级菜单并设置菜单名称、路径和权限。

确认信息无误后点击“确定提交”。提交后回到版本管理或发布设置页，完成版本发布操作。发布前重点检查：

• 制品标识和版本号是否正确。
• 后端包、前端包或 YAML 是否已上传。
• 代码配置类型是否选择正确，传统应用和 K8sYaml 是否跳过了原生应用配置。
• K8sYaml 的 Helm 包、安装配置和额外 YAML 是否属于同一版本。
• 入口菜单、接口地址、网关域名转发规则是否和应用实际路径一致。
• 启动参数、网关域名转发规则、安装依赖和环境变量是否适用于生产环境。
• 子应用是否已按主应用相同的代码配置类型规则补齐配置。
• 版本说明是否能让用户理解本次更新内容。

菜单配置建议：

配置项	说明
一级菜单	应用有独立管理页面时添加；纯后端能力通常不需要菜单
菜单名称	使用用户能理解的业务名称
菜单路径	和前端路由入口一致，避免发布后打开空白页
权限角色	和前端包配置中的角色保持一致

发布前建议执行一次完整预览：

1. 从版本管理页确认开发版本配置完整。
2. 检查网关域名转发设置，确认后端请求路径、转发目标和匹配规则正确。
3. 确认前端入口和菜单路径一致。
4. 确认发布设置中的目标版本是本次要发布的版本。
5. 提交发布后，在应用市场或安装入口验证版本是否可见。

发布后验证

发布完成后，不要只看发布状态，还需要验证用户实际安装和打开路径。

验证项	预期结果
应用市场可见	应用名称、图标、版本号和描述显示正确
安装流程	安装参数、默认值和必填项符合预期
后端服务	Pod 正常运行，健康检查通过，日志无启动错误
前端入口	菜单能打开页面，iframe 或微应用加载正常
API 请求	前端能访问应用 API，网关域名转发规则、请求头和 Query 参数生效
子应用	子应用实例、端口、转发规则和依赖关系符合配置
升级流程	从旧版本升级到新版本后配置不丢失

如果发布后发现问题，优先在开发版本中修正配置并重新提交。已发布版本涉及用户安装时，避免直接覆盖不兼容配置，应新建修复版本并在版本说明中写清楚影响范围。

常见问题

问题	处理方式
标识校验失败	检查 w7- 后面的业务标识是否包含 - 或 _，如需分词使用纯字母数字命名
前端入口空白	确认前端包根目录包含 index.html，并检查控制台入口路径
接口请求失败	检查接口地址、网关域名转发设置、请求头和 Query 参数是否和应用代码一致
菜单不显示	检查是否上传前端包并配置管理端、菜单、角色权限和发布状态；纯后端制品不会展示前端菜单
发布后版本不对	回到版本管理页确认当前线上版本和开发版本