目录中心化与版本形态

这一页讲 wujies-app-market 里两个部署拓扑开关的语义、互相约束与失败表现：

两者互相牵制：edition=client 必须配 catalog.mode=remote，否则启动直接失败。组合错了有两种坏结果 —— 起不来，或者更糟的看着成功、实际无效（在用户版的上架端"上架成功"，而安装读的是远端目录）。

要装这样的多套部署（1Panel 包、端口、令牌分发、链路验证）见 /deploy/multi-deployment；每一项配置的默认值与环境变量名见 /deploy/configuration 与 /reference/config；本页讲的是代码里为什么这么写、改哪一行会坏什么。

一、目录中心化（app-market.catalog.mode）复制标题链接

1.1 前提：三类数据必须先分家复制标题链接

三种数据混在同一套表里，才会出现"多部署一套系统，上架一次要同步 N 遍"。它们的边界是表上有没有 tenant_id，判据落在两处：DDL 在 wujies-platform/script/sql/update/app_market.sql，全局表白名单在 wujies-platform/wujies-admin/src/main/resources/application.yml 的 security.tenant.excludes。

因为目录这几张表不带租户参数，目录接口 /app/catalog/** 的请求里不需要传租户 —— 这是整件事能干净做掉的原因，也是"目录能被搬到另一台机器"的全部前提。表间关系见 /design/data-model。

1.2 唯一入口：IAppCatalogService复制标题链接

安装侧的代码只允许通过它读目录，不要直接注入 AppInfoMapper / AppVersionMapper。接口是"按业务语义取用"而不是"把 Mapper 包一层"，所以远程实现只用 URL + 参数就能做出来，不必把 LambdaQueryWrapper 这种本地 ORM 概念漏到远端。

契约共 9 个方法（wujies-platform/wujies-modules/wujies-app-market/src/main/java/cn/wujies/appmarket/catalog/IAppCatalogService.java），每个都有真实消费方：

AppPackageDeployService.deploy(...) 里的两处调用是"这条规矩的主路径"：以前它直接 selectById 读 app_version / app_info，远程模式下本地没有目录数据，安装会在"下载并落位"这一步报"版本不存在"。

1.3 两种实现怎么二选一复制标题链接

remote 与 local 用 @ConditionalOnProperty 二选一，刻意不用 @ConditionalOnMissingBean —— 后者依赖 bean 定义的先后顺序，换个扫描顺序就可能两个都在或两个都不在，而条件属性是确定的。

app-market:
  catalog:
    mode: local                 # local（默认，直连本库） / remote（走 base-url）
    base-url: ''                # mode=remote 时必填，否则启动失败
    token: ''                   # 服务间共享令牌，两端要一致；服务端留空 = 不校验调用方
    connect-timeout-ms: 3000    # 只被 remote 实现读
    read-timeout-ms: 15000      # 只被 remote 实现读

除了 base-url 的构造期检查，还有一道形态自洽检查（edition/MarketEditionStartupCheck，@PostConstruct）：edition=client 时 catalog.mode 不是 remote、或 base-url 为空，都直接启动失败并写出该改哪一行。理由见 2.2 第 3 条。

日志是核对"到底装配了哪个"最快的办法，RemoteAppCatalogService 构造时打：

目录访问走远程服务: https://<host>（超时 连接3000ms / 读取15000ms，令牌已配置）

1.4 服务间接口 /app/catalog/**复制标题链接

9 个端点的路径、参数、权限逐条见 /reference/api；令牌的安全边界（明文请求头、只防误连与扫描器）见 /ops/backup-security。

1.5 远程实现的四个坑复制标题链接

四个坑都真实踩过，处理方式写在 catalog/RemoteAppCatalogService 的类注释里：

第 3 条的判据很好记：英文能搜到、中文搜不到，就是编码问题。

1.6 刻意不做缓存复制标题链接

目录读取的频率是"安装 / 升级 / 逛市场时几次"，不是热路径；而目录的写入发生在另一个部署里，本地根本感知不到，加缓存只能靠 TTL 猜 —— 那会让"刚上架却装到旧版本"变得不可解释。宁可每次直查：慢一点，但结果可解释。

同理，"应用市场"的列表 / 详情 / 版本三个页面也一并收口到目录接口（AppMarketController 的 searchOnShelf / findApp / releasedVersions）。不收口的话远程模式下能装但逛不了市场：安装走远端目录、市场页却读本地那份过期或空的目录。

二、版本形态（app-market.edition）复制标题链接

2.1 两个角色差在哪复制标题链接

同一套代码扮演两个角色，刻意不做 fork：本项目有三个仓库（后端 wujies-platform、宿主前端 plus-ui、插件仓库 wujies-plugins，见 /design/repo-layout）、一批 SQL 脚本，以及一堆构建期约定（远程应用要复刻宿主的自动导入与组件解析器，见 /advanced/remote-app）。fork 之后每次改公共逻辑都要改两遍，而且必然漂移。

用户版不是阉割版，它只是不上架。

2.2 三个刻意的设计复制标题链接

1）用过滤器按路径前缀挡上架端，不是给控制器逐个加注解。 edition/MarketEditionGuardFilter（OncePerRequestFilter）匹配 MarketEdition.PUBLISH_PREFIXES 这四个前缀：

好处是以后新增上架端接口会自动被挡住，不会因为"忘了加开关"漏出去。

2）返回 403 + 明确文案，不是 404、更不是静默失效。 用户版的上架端写的是本地库，而安装读的是远端目录 —— 放开的话"上架成功"对安装毫无影响，这是最坏的一种失败（看着成功、实际无效）；404 则会把人引向路由与网络排查。响应体与 GlobalExceptionHandler 同结构：

{
  "code": 403,
  "msg": "本版本不含「应用上架」功能（app-market.edition=client）。应用由官方统一上架，本机通过 app-market.catalog.base-url 从官方目录读取。",
  "data": null
}

拒的是过滤器，而登录检查走的是 MVC 拦截器（SaInterceptor；全项目唯一的 SaServletFilter 只覆盖 /actuator/**，见 wujies-common-security 的 SecurityConfig）。所以用户版下不带 token 打上架端接口，先拿到的是 403 而不是 401 —— 这正好可以用来区分"被形态闸门拦了"和"确实没登录"。

3）启动期校验形态与目录配置自洽。 edition/MarketEditionStartupCheck 在 @PostConstruct 里判定，不自洽就直接启动失败并写明该改哪一行：

拦这个的理由：client + local 是"能起来但什么都装不了"的组合（市场列表读本地空目录、安装报"应用版本不存在"），根因在任何一个报错里都看不出来。

启动日志里也能直接读到形态（官方版/用户版各一句），配合 1.3 里那条远程目录日志，就能确认"这台到底是什么形态、目录从哪来"。

2.3 用户版的前端半边复制标题链接

用户版的 sys_menu 里仍然有那几行上架菜单（平台初始化 SQL 建的，存量部署改不动），所以不能靠"初始化 SQL 不插那几行"解决。现在是服务端隐藏 + 前端兜住：

AppMenuFilterImpl.enabled() 在用户版直接 return true（不查"目录里有没有已上架应用"）：要隐藏的上架端菜单是平台 SQL 建的，与目录里有没有应用无关；短路掉的话，刚部署好、还没上架任何应用的用户版会看到一整套点了就 403 的菜单。

2.4 取值怎么被规范化复制标题链接

MarketEdition 用 StringUtils.trim + equalsIgnoreCase 判定，因此：

• 大小写不敏感（Client、CLIENT 都算用户版）；
• 任何非 client 的值都按 official 处理，不报错（写错了不会在启动时报出来，只会"看起来还是官方版"）；
• GET /app/edition 返回的是 name() 规范化后的值（只可能是 official / client）。

三、两个开关的组合复制标题链接

一台官方版可以同时给多个用户版供目录；拓扑怎么选、包怎么装见 /deploy/multi-deployment。

四、怎么核对复制标题链接

# 1) 形态自述：任何已登录用户的 token 都能调；用户版应为 {"edition":"client","consoleVisible":false}
curl.exe -H "Authorization: Bearer <token>" http://localhost:8080/app/edition

# 2) 上架端闸门：用户版下应为 403（且响应体里的 msg 点明是 edition=client 导致的）
curl.exe -s -o NUL -w '%{http_code}\n' http://localhost:8080/app/console/list

# 3) 目录服务自测（令牌 = app-market.catalog.token；服务端留空时可不带头）
curl.exe -H "X-Catalog-Token: <token>" "http://<目录服务>:8080/app/catalog/count-on-shelf"

# 4) 中文搜索自检：英文能搜到、中文搜不到 = URI 二次编码那个坑（见 1.5）
curl.exe -H "X-Catalog-Token: <token>" --get --data-urlencode "keyword=图床" `
  "http://<目录服务>:8080/app/catalog/market-search"

启动日志里找这三类行，就能确认形态与目录实现：应用市场版本形态: official（目录 local，本机含上架端） / 应用市场版本形态: client（不含上架端，目录走远端 ...） / 目录访问走远程服务: ...。

报错对照与排查路径见 /ops/troubleshooting，安装/升级任务里的失败原因见 /ops/task-center。

相关阅读复制标题链接

• 应用市场模块 —— catalog/ 与 edition/ 两个包在模块里的位置
• 多部署与目录服务 —— 怎么真的装起"一台目录服务 + 多个安装方"
• 部署配置安全清单 —— app-market: 三块的部署期清单
• 配置项索引 —— catalog.* 与 edition 的默认值与消费方
• 应用市场 API —— /app/catalog/** 9 个端点与 GET /app/edition
• 数据模型 —— 目录 / 安装实例 / 迁移记录三类数据的边界
• 应用生命周期 —— 安装 / 升级 / 卸载里哪几步在读目录