常见问题

本页汇总部署与开发中的高频问题及排查方法。

端口 / 404

后端启动了但前端请求 404 / 连不上后端

原因：端口用错了。旧文档写「后端 8080 / 前端 5173」是过时的。

实际端口（以配置文件为准）：

后端：52856（backend/src/main/resources/application.yml 中 server.port: 52856）
前端：3000（frontend/vite.config.ts 中 server.port: 3000）

排查：

确认后端进程监听 52856：lsof -i:52856 或 curl http://127.0.0.1:52856/api/system/health。
确认前端 vite.config.ts 中代理 target: 'http://127.0.0.1:52856'。
访问 http://localhost:3000（不是 5173）。

详见。

接口报 404，请求路径里有两个 /api

原因：双重 /api 前缀。

前端 axios baseURL = '/api'，后端控制器 @RequestMapping("/api/xxx")，代理保留 /api 透传。前端 api 模块的请求路径不应再带 /api。

写法	实际请求	结果
`request.get('/database/...')`	`/api/database/...`	✅
`request.get('/api/database/...')`	`/api/api/database/...`	❌ 404

修复：检查 frontend/src/api/*.ts，去掉请求路径里多余的 /api。详见。

Docker 部署后 frontend 容器 502 Bad Gateway

原因：后端容器实际监听 52856，但 Dockerfile EXPOSE 8080、docker-compose 映射 8080:8080、nginx.conf 反代到 backend:8080，端口不一致。

修复：给 backend 服务加 SERVER_PORT: 8080 环境变量让应用监听 8080，或将 Dockerfile / compose / nginx 全部改为 52856。详见。

数据库

H2 重启后数据全没了

原因：H2 是内存库（jdbc:h2:mem:lowcode），进程结束数据丢失，这是正常行为。

解决方案：

需要持久化请改用 MySQL（参考）。
H2 每次启动会重新执行 schema-h2.sql + data-h2.sql，所以基础数据会恢复，但你运行时新增的数据会丢。

MySQL 启动后报「表不存在」（Unknown table）

原因：MySQL 没有导入完整 SQL。application-mysql.yml 中 mode: never 不会自动建表，且 schema-mysql.sql 只有 16 张表。

修复：按推荐组合导入完整 SQL：

mysql -u root -p lowcode < docs/SQL_INIT.sql
mysql -u root -p lowcode < docs/SQL_EXTENSION.sql
mysql -u root -p lowcode < sql/mysql/bpm.sql
mysql -u root -p lowcode < sql/mysql/hr_employee.sql
mysql -u root -p lowcode < backend/src/main/resources/data-mysql.sql
mysql -u root -p lowcode < sql/mysql/migration-column-meta-options.sql

详见。

schema-mysql.sql 导入后还是缺表

schema-mysql.sql 只有 16 张表，不要单独使用。它远落后于 schema-h2.sql（53 张）。MySQL 初始化请用上述推荐组合，或参考 schema-h2.sql 转换（注意 H2 与 MySQL 语法差异，如 CLOB -> TEXT）。

报 Unknown column 'options_api' 等

原因：旧库的 lc_column_meta 表缺少远端选项列（options_api / option_value / option_label / display_prop）。

修复：执行幂等迁移脚本 sql/mysql/migration-column-meta-options.sql，可重复执行。

BPM 表报缺少 create_by / update_by 列

原因：芋道风格 BPM 表（bpm_category / bpm_form 等）原生没有 create_by / update_by 列，但 BaseEntity 自动填充需要。

修复：执行 backend/src/main/resources/data-mysql.sql（内含 ALTER TABLE ... ADD COLUMN IF NOT EXISTS create_by ...）。

登录 / 密码

admin 登录不上，密码不对

原因：不同 profile 默认密码不同。

环境	默认密码	来源
H2（开发）	`123456`	`data-h2.sql` 种子
MySQL 首次启动	`admin123`	`DataInitializer.initAdminUser()`
新建租户	`123456`	`DataInitializer.initTenantAdmin()`

MySQL 首次密码可通过启动参数覆盖：java -Dapp.admin.password=你的密码 -jar ...。详见。

登录返回 401 / 未授权

原因：JWT 未携带或已过期。

排查：

登录后前端应把返回的 token 存到 localStorage / Pinia，并在后续请求 Header 加 Authorization: Bearer <token>。
JWT 有效期 24 小时（86400000ms），过期需重新登录。
若所有接口都 401，检查 SecurityConfig 白名单是否放行了该路径。

编译 / 构建

Maven 构建报 TypeTag / Lombok 错误

原因：JDK 21 + Maven 命令行环境下 Lombok 注解处理失败（Lombok 与高版本 JDK 兼容性问题）。

解决方案（任选）：

用 JDK 17（推荐）：项目编译目标即 17。
用 IntelliJ IDEA 编译（内置编译器兼容性更好）。
用 javac --add-opens jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED ...。

Lombok 版本 1.18.36。详见。

前端依赖安装失败 / 版本冲突

项目含 pnpm-workspace.yaml，推荐用 pnpm。若用 npm 装过导致冲突：

cd frontend
rm -rf node_modules package-lock.json
pnpm install

Docker 构建时 frontend/Dockerfile 已用 node:20-alpine + npmmirror 镜像源。

后端改了代码不生效

原因：backend/pom.xml 未引入 spring-boot-devtools，后端无自动热重载。

解决：以 Debug 模式运行 IDEA 用 Reload Changed Classes，或手动重启后端，或引入 spring-boot-devtools。详见。

安全 / 多租户

JWT 到底有没有强制校验？旧文档说 permitAll

以代码为准：当前 SecurityConfig.java 对业务接口采用 anyRequest().authenticated()，JWT 是强制校验的，未携带有效 token 会返回 401/403。早期文档/记忆提到的「permitAll、JWT 未强制」对应更早版本，已不适用。

公开白名单（无需认证）：/api/auth/login / /captcha / /register / /api/auth/sso/** / /api/open/** / /api/mobile/** / /uploads/** / /upload/**。

残留风险（二次开发需注意）：

方法级 @PreAuthorize 覆盖不完整，部分接口登录即可访问。
角色权限树部分硬编码。
jwt.secret 是默认公开值，生产必须改。

详见。

多租户数据串号 / 看到别的租户数据

原因：TenantContext（ThreadLocal）未正确清理或传递。

排查：

JwtAuthenticationFilter 在 finally 中调用了 TenantContext.clear()，正常请求不会串号。
若你用了 @Async / 线程池 / 手动开线程，ThreadLocal 不会自动传递，需手动 TenantContext.setTenantId(...) 并在结束时 clear()。
系统表白名单（sys_tenant / sys_user / sys_role / sys_menu / sys_user_role / sys_role_menu）不追加 tenant_id 条件，属正常。

详见。

生产环境安全检查清单

[ ] jwt.secret 改为随机强密钥
[ ] MySQL 密码修改（非 Admin123. / root）
[ ] Redis 换成自有实例（默认连远程 124.71.29.50:6379）
[ ] 补充敏感接口的 @PreAuthorize 注解
[ ] 确认 SecurityConfig 白名单无多余放行

详见。

Redis

后端启动报 Redis 连接失败

原因：默认连远程 Redis 124.71.29.50:6379，网络不通或密码变更。

处理：

Redis 非必须：防抖 / 限流 / 缓存功能会降级（fail-open: true），核心业务可启动。若启动直接失败，检查是否硬依赖。
配置自有 Redis：export REDIS_HOST=你的地址 REDIS_PORT=6379 REDIS_PASSWORD=你的密码。
关闭防抖：export API_DEBOUNCE_ENABLED=false。

其他

上传文件报 413 / 文件太大

原因：Nginx 默认 client_max_body_size 为 1MB。

修复：Nginx 配置加 client_max_body_size 50M;（与后端 max-request-size: 50MB 对齐）。详见。

H2 控制台打不开

确认以 h2 profile 启动（application-h2.yml 中 spring.h2.console.enabled: true）。控制台路径 http://localhost:52856/h2-console，JDBC URL 填 jdbc:h2:mem:lowcode，用户名 sa，密码空。

找不到某张表（运行时表）

部分表（sys_role_field_permission / sys_audit_log / lc_form_version / lc_api_key / fnd_* 等）没有独立 .sql 文件，由 DataInitializer / FoundationSeeder 在启动时 CREATE TABLE IF NOT EXISTS 创建。确认应用已正常启动，这些表会自动生成。完整清单见。

更多环境差异见。