# 本地运行 xlyEntry

本页是开发者上手路径：克隆仓库，在本机启动 `xlyEntry`，并访问一个框架端点。配套的[多服务部署](deployment.md)页面覆盖运维视角（多服务、profile 组合、nginx）。

## 前置条件

| 工具 | 版本说明 |
|---|---|
| JDK 8 | `xly-src/build.gradle` 固定 `sourceCompatibility = 1.8`。JDK 11+ 尚未验证。 |
| Gradle wrapper | 仓库已包含（`./gradlew`）。不要单独安装 Gradle。 |
| MySQL 8 | 驱动为 `com.mysql.cj.jdbc.Driver`。你的 DB schema 必须和 active profile yaml 指向的 schema 匹配；见下面“DB 覆盖”。 |
| Redis | `local` profile 期望 `127.0.0.1:16379`，密码为 `xlyXLY2015`（见 `xlyEntry/src/main/resources/application-local.yml`）。 |
| ActiveMQ + MongoDB | `local` profile 中两者都指向 `t0.xlyprint.com`。如果你的网络能访问该主机，就不需要本地运行它们。 |

自动目录生成器（`scripts/gen_catalog.py`）和运行 xly 无关；它只通过 `~/.my.cnf` 读取 schema 元数据。该路径见[参与维护](../../contributing/index.md)。

## DB 覆盖

仓库中的 `xlyEntry/src/main/resources/application-local.yml` 的 `spring.datasource.url` 指向远程开发库。大多数开发者会把它覆盖到本地或个人目标。有两个选择：

1. **直接编辑 yaml。** 不要提交这个改动。
2. **通过 JVM 参数覆盖。** 调用 `bootRun` 时传 `-Dspring.datasource.url=...`。

Wiki 的侦察脚本通过 `~/.my.cnf` 使用 `xlyweberp_saas_ai`，这和 `application-local.yml` 默认的 `xlyweberp_saas` **不是同一个** schema。选一个 schema，并保持一致。

## 运行

从 `xly-src/` 目录执行：

```bash
./gradlew :xlyEntry:bootRun -Dspring.profiles.active=local
```

`xlyEntry` 会打成 WAR（见它自己的 `build.gradle`），但开发时 `bootRun` 使用的是 Spring Boot 内嵌 Tomcat，因此不需要外部 Tomcat 部署。

## 冒烟检查

启动完成后（日志中出现 `Tomcat started on port(s): 8080`）：

| URL | 预期结果 |
|---|---|
| `http://localhost:8080/xlyEntry/` | 框架落地页。未认证页面可以渲染；需要认证的页面会跳到 `/login`。 |
| `http://localhost:8080/xlyEntry/druid/` | Druid 数据源监控。默认凭据 `xly` / `666666` 在 yaml 中；对外暴露端口前必须修改。 |

如果冒烟检查失败，查看 active profile yaml 中 `logging.dirpath` 配置的日志目录。

## `local` 包含什么，不包含什么

`local` profile **只**启动框架运行时。它不会启动：

- `xlyApi` — 如果需要外部 API 接口面，请作为第二个 JVM 启动。
- `xlyInterface` — 同上。
- `xlyPlc`、`xlyFlow`、`xlyFace` — 同上；每个服务都有自己的 application class 和 profile。
- `xlyErpJms*` consumer — 它们是独立的 Spring Boot app。没有它们，跨节点的基础数据合并 / 消息扇出不会发生；元数据保存后的 Redis 缓存清理由 BACK 侧同步 `@CacheEvict` 完成，单节点开发机通常可以接受。

多服务本地开发见[多服务部署](deployment.md)。

## 启动失败时

最常见的两类失败：

1. **`Communications link failure`** — `spring.datasource.url` 目标在你的机器上不可达。按“DB 覆盖”中的方法覆盖它。
2. **`Connection refused: t0.xlyprint.com:61616` 或 `:27017`** — 你的网络无法访问共享开发基础设施。你可以接入正确网络，把 yaml 指向本地实例，或在调试期间注释掉相关 bean。