Flowable UI中REST端点配置失败的常见原因有哪些？

Question

Flowable UI中REST端点配置失败的常见原因主要包括：1）**基础URL配置错误**——`flowable-ui-app.properties`中`flowable.common.app.rest-base-url`未正确指向已启动的Flowable REST应用（如`http://localhost:8080/flowable-rest`），或路径末尾遗漏`/rest`；2）**跨域限制（CORS）**——REST服务未启用CORS，导致UI发起的AJAX请求被浏览器拦截；3）**认证不匹配**——UI默认使用HTTP Basic认证，而REST服务启用了JWT、OAuth2或禁用了Basic，造成401响应；4）**Spring Security拦截**——自定义安全配置误拦截`/app/rest/**`等端点；5）**服务未就绪或端口冲突**——REST应用未启动、健康检查失败，或端口被占用。排查建议：先通过浏览器直访`{rest-url}/app/rest/server`验证连通性与响应状态码，并检查UI浏览器控制台及REST服务日志中的具体错误信息。

Answer 1

```html

一、现象层：UI界面无响应或持续加载，控制台报 Failed to load resource: net::ERR_CONNECTION_REFUSED 或 404 Not Found

这是最表层的症状，通常在首次集成 Flowable UI 与 REST 后立即暴露。用户点击“流程定义”“任务列表”等模块时空白或弹出“无法连接到后端服务”。此时尚未涉及认证或安全逻辑，仅反映网络可达性与基础路由映射失败。

二、配置层：flowable-ui-app.properties 中 REST 基础 URL 错误（含路径语义陷阱）

• flowable.common.app.rest-base-url=http://localhost:8080/flowable-rest —— ❌ 缺少 /rest 路径段，正确应为 http://localhost:8080/flowable-rest/rest；
• 若 REST 应用上下文路径为 /flowable-api，则必须严格匹配：http://localhost:8080/flowable-api/rest；
• URL 末尾是否带斜杠影响 Spring MVC 的路径匹配行为（尤其在反向代理场景下），建议统一采用 .../rest/ 格式。

三、网络与协议层：CORS 策略拦截与预检请求（OPTIONS）失败

浏览器控制台可见 Access to fetch at '...' from origin 'http://localhost:8080' has been blocked by CORS policy。Flowable REST 默认未启用 CORS，需在 application.yml 显式配置：

spring:
  web:
    cors:
      allowed-origins: "http://localhost:8080"
      allowed-methods: "GET,POST,PUT,DELETE,OPTIONS"
      allowed-headers: "*"
      allow-credentials: true

四、安全认证层：HTTP Basic 认证不兼容引发的 401 循环

UI 默认行为	REST 实际配置	典型错误码	根本原因
自动携带 Authorization: Basic YWRtaW46dGVzdA==	禁用 Basic，仅支持 JWT Bearer	401 Unauthorized	UI 无 Token 获取机制，无法构造有效 JWT
不发送任何认证头	强制 Basic 认证且未提供凭据	401 + WWW-Authenticate header	Spring Security 拦截未认证请求

五、框架集成层：Spring Security 自定义配置误伤 Flowable REST 端点

常见错误配置示例：

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(authz -> authz
        .requestMatchers("/app/**").authenticated() // ✅ 正确：保护 UI 静态资源
        .requestMatchers("/rest/**").permitAll()     // ❌ 错误：Flowable REST 实际路径是 /app/rest/**
        .anyRequest().authenticated()
    );
}

正确路径应为 /app/rest/**（由 Flowable Common App 自动注册），否则请求被 FilterChainProxy 拦截并返回 403。

六、运行时可观测性：端点健康检查与日志诊断链路

graph TD
    A[UI 浏览器访问 /app/rest/server] --> B{HTTP 状态码}
    B -->|200 OK| C[解析 JSON：serverInfo.version]
    B -->|404| D[检查 REST 应用是否部署？上下文路径是否匹配？]
    B -->|503| E[查看 REST 日志：DataSource 连接失败？Camunda DB 初始化异常？]
    B -->|401/403| F[比对 UI credentials 与 application.yml security config]

七、进阶排查：使用 curl 模拟 UI 请求，绕过浏览器干扰

执行以下命令验证底层连通性与认证流：

curl -v -u admin:test http://localhost:8080/flowable-rest/rest/server

重点关注：< HTTP/1.1 200、Content-Type: application/json、响应体中 "version" 字段。若失败，-v 输出将揭示重定向、认证挑战头或 SSL 握手问题。

八、生产就绪检查清单（Checklist）

• ✅ REST 应用进程存活（ps aux | grep flowable-rest）且监听预期端口（netstat -tuln | grep :8080）
• ✅ /actuator/health 返回 {"status":"UP"}
• ✅ Flowable UI 的 flowable.common.app.rest-base-url 在 JVM 启动参数或外部配置中心中已覆盖
• ✅ Nginx/Apache 反向代理配置中，proxy_pass 尾部斜杠与路径重写逻辑一致（避免双 //）
• ✅ 数据库连接池（HikariCP）未耗尽，show full processlist; 无长事务阻塞

九、架构视角：为何 Flowable 将 UI 与 REST 物理分离？

这种设计源于企业级 BPM 平台的弹性治理需求：UI 可独立部署于 CDN 或前端服务器，REST 服务可水平扩展并接入统一 API 网关（如 Kong、Spring Cloud Gateway）。但分离也放大了跨域、认证上下文传递、版本兼容性等运维复杂度——这正是资深工程师需掌握的“分布式系统契约意识”。

十、延伸思考：当 Flowable REST 与 Keycloak 集成后，UI 如何适配？

此时需改造 UI 的认证流程：禁用 Basic，引入 keycloak-js SDK，在 index.html 初始化 Keycloak 实例，并通过 KeycloakBearerInterceptor 自动注入 Authorization: Bearer <token>。同时 REST 端需配置 keycloak.securityConstraints 并启用 keycloak.bearer-only=true，形成 OAuth2 Resource Server 安全模型。

```