# LIGHT CHASER 部署运维说明

本文面向生产部署和日常运维，说明如何启用 `lc-server`、如何调整配置文件、如何查看日志，以及如何升级和回滚。当前仓库的主库部署方案以 SQLite 为准，本文不描述主库切换到其他数据库的场景。

## 交付物

同源发布脚本会在 `backend/target/` 下生成两个核心产物：

- `lc-server.jar`
- `lc-server-release.zip`

压缩包内默认包含：

- `lc-server.jar`
- `部署运维说明.md`

## 目录建议

建议在服务器上准备如下目录结构：

```text
/usr/app/light-chaser-server/
  lc-server.jar
  config/
    application.yml
    log4j2-spring.xml   # 可选，只有需要自定义日志时才放
  data/
  logs/
  tmp/
```

建议含义如下：

- `config/`：外部配置文件目录
- `data/`：数据库文件、项目资源目录、上传内容等持久化数据
- `logs/`：运行日志目录
- `tmp/`：临时文件目录

## 如何启用

### 访问地址

服务启动成功后，直接访问：

```text
http://<服务器IP>:8080/
```

本地启动时就是：

```text
http://localhost:8080/
```

如果你想直接进入控制台，也可以访问：

```text
http://<服务器IP>:8080/home/console
```

### 方式一：直接启动

适合本地验证或临时上线。

```bash
cd /usr/app/light-chaser-server
java -jar lc-server.jar --spring.config.additional-location=file:/usr/app/light-chaser-server/config/
```

说明：

- `spring.config.additional-location` 用于追加外部配置目录，不会覆盖 jar 内置默认配置
- 如果你希望完全使用外部配置，也可以改成 `--spring.config.location=file:/usr/app/light-chaser-server/config/application.yml`
- 服务默认监听 `8080`

### 方式二：后台常驻

适合 Linux 服务器手工托管。

```bash
cd /usr/app/light-chaser-server
nohup java -Xms512m -Xmx1024m -jar lc-server.jar \
  --spring.config.additional-location=file:/usr/app/light-chaser-server/config/ \
  > logs/console.log 2>&1 &
```

说明：

- 标准输出会被重定向到 `logs/console.log`
- 同时，`log4j2-spring.xml` 还会把业务日志写入 `logs/` 目录

### 方式三：systemd 托管

适合生产服务器启停和开机自启。

示例 `/etc/systemd/system/lc-server.service`：

```ini
[Unit]
Description=LIGHT CHASER Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/usr/app/light-chaser-server
ExecStart=/usr/lib/jvm/jdk-17/bin/java -Xms512m -Xmx1024m -jar /usr/app/light-chaser-server/lc-server.jar --spring.config.additional-location=file:/usr/app/light-chaser-server/config/
Restart=always
RestartSec=5
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target
```

启用命令：

```bash
systemctl daemon-reload
systemctl enable --now lc-server
```

常用命令：

```bash
systemctl status lc-server
systemctl restart lc-server
systemctl stop lc-server
journalctl -u lc-server -f
```

## 如何调整配置文件

### 外部配置文件位置

推荐把外部配置放在：

```text
/usr/app/light-chaser-server/config/application.yml
```

如需自定义日志行为，也可额外放：

```text
/usr/app/light-chaser-server/config/log4j2-spring.xml
```

### 配置项说明

| 配置项 | 作用 | 建议 |
|---|---|---|
| `spring.datasource.url` | 数据库连接地址 | 默认 SQLite 本地文件，部署时保持该配置即可 |
| `spring.datasource.username/password` | 数据库账号密码 | SQLite 下通常留空 |
| `light-chaser.project-resource-path` | 项目资源根目录 | 建议指向持久化且可写的目录，例如 `/usr/app/light-chaser-server/data`，自动生成的 RSA 密钥也会保存在这里 |
| `light-chaser.migration.enable` | 是否启动时执行迁移 | 首次部署建议 `true`，稳定后可按需调整 |
| `light-chaser.ai.enabled` | 是否启用 AI 功能 | 默认 `true`，如果不需要 AI 可改为 `false` |
| `light-chaser.ai.models` | AI 模型列表 | 至少配置一个可访问的 OpenAI 兼容模型 |
| `light-chaser.crypto.rsa.public-key-path` | RSA 公钥文件路径 | 默认位于 `project-resource-path/keys/public_key.pem`，启动时若不存在会自动生成 |
| `light-chaser.crypto.rsa.private-key-path` | RSA 私钥文件路径 | 默认位于 `project-resource-path/keys/private_key.pem`，启动时若不存在会自动生成 |
| `light-chaser.crypto.aes.key` | AES 密钥 | 保持和前端约定一致 |
| `logging.config` | 日志配置文件 | 默认使用 jar 内置 `classpath:log4j2-spring.xml` |

> 注意：RSA 密钥是数据源密码加解密所依赖的持久化密钥对。首次启动时如果 `project-resource-path/keys` 不存在，系统会自动生成并写入该目录。请务必把这个目录纳入备份，否则历史加密数据将无法继续解密。

### SQLite 示例

```yaml
spring:
  datasource:
    driver-class-name: org.sqlite.JDBC
    url: jdbc:sqlite:/usr/app/light-chaser-server/data/lc-server.db

light-chaser:
  project-resource-path: /usr/app/light-chaser-server/data
  migration:
    enable: true
  ai:
    enabled: true
    models:
      - id: default
        label: 默认模型
        provider: openai-compatible
        model-name: gpt-4o-mini
        base-url: https://api.openai.com/v1
        api-key: your-api-key
        api-key-header: Authorization
        api-key-prefix: Bearer
        chat-completions-path: /chat/completions
        enabled: true
        is-default: true
        temperature: 0.3
        max-tokens: 2048
```

### AI 功能说明

当前开源版提供模型管理页和两类 AI 场景：

- 模型管理：用于配置可调用的 AI 模型，不包含 AI 生成组件功能
- 样式优化：只修改组件 `style`
- 数据优化：只修改组件已有的数据配置

其中，数据优化只支持开源版已有的数据源类型：

- `static`
- `api`
- `database`

不支持新增 `excel` 或其他桌面端专有的数据源类型。

### 自定义日志配置

默认日志配置写在 jar 内部的 `classpath:log4j2-spring.xml`，日志输出到当前启动目录下的 `logs/`。

如果你想改日志目录或级别，推荐把 `log4j2-spring.xml` 复制到外部配置目录后再覆盖：

```yaml
logging:
  config: file:/usr/app/light-chaser-server/config/log4j2-spring.xml
```

## 如何查看日志

### 日志文件位置

默认日志文件位于启动目录下的 `logs/`：

- `logs/console.log`：如果你使用 `nohup` 重定向，标准输出会进入这里
- `logs/test.log`：启动时清空，适合临时排查
- `logs/info.log`：常规信息日志
- `logs/warn.log`：警告日志
- `logs/error.log`：错误日志

说明：

- `test.log` 在当前配置里是 `append=false`，每次启动会覆盖
- `info.log`、`warn.log`、`error.log` 都会按大小和时间滚动归档

### 常用查看命令

```bash
tail -f logs/info.log
tail -f logs/warn.log
tail -f logs/error.log
```

如果是 systemd 托管：

```bash
journalctl -u lc-server -f
```

如果是 Docker 托管：

```bash
docker logs -f lc-server
```

## 如何升级

推荐升级流程：

1. 备份 `config/`、`data/` 和当前 `lc-server.jar`
2. 停止当前服务
3. 替换新的 `lc-server.jar`
4. 检查外部配置是否需要更新
5. 启动服务并观察日志

示例：

```bash
systemctl stop lc-server
cp /tmp/new/lc-server.jar /usr/app/light-chaser-server/
systemctl start lc-server
tail -f logs/info.log
```

## 如何回滚

如果新版本启动失败或出现业务异常，优先回滚 jar：

```bash
systemctl stop lc-server
cp /usr/app/light-chaser-server/backup/lc-server.jar /usr/app/light-chaser-server/lc-server.jar
systemctl start lc-server
```

回滚时通常不需要动 `config/` 和 `data/`，除非新版本修改了配置结构或数据结构。

## 常见问题

### 1. 启动时报 Java 版本不对

报错类似：

```text
Java 17+ is required for the backend build
```

处理方式：

- 确认服务器安装了 JDK 17
- 使用 `JAVA_HOME` 或 `--java-home` 指向 JDK 17
- systemd 启动时直接写死 JDK 17 的 `java` 路径

### 2. 端口 8080 被占用

处理方式：

```bash
lsof -i :8080
kill -9 <pid>
```

或者修改外部配置中的 `server.port`。

### 3. 数据库文件或资源目录无法写入

处理方式：

- 确认 `light-chaser.project-resource-path` 指向了可写目录
- 确认运行用户对 `data/` 和 `logs/` 有写权限

### 4. 前端刷新出现 404

处理方式：

- 确认你部署的是同源版 `lc-server.jar`
- 确认 `backend/src/main/resources/static/index.html` 已被打入 jar
- 确认访问路径是 `/`、`/home/console`、`/designer` 等前端路由，而不是接口路径

### 5. 首页访问出现 500

处理方式：

- 确认你访问的是 `/` 或 `/home/console`
- 确认运行的是最新的同源发布包，而不是旧版 `lc-server.jar`
- 查看 `logs/error.log`，如果仍然看到 `forward:/index.html` 相关异常，说明当前进程没有换成最新包
- 如果 `index.html` 被误删或没有打包进 jar，也会导致首页无法打开

### 6. AI 面板没有可用模型

处理方式：

- 确认 `light-chaser.ai.enabled` 为 `true`
- 确认模型管理页中至少配置了一个可用模型，或者在 `light-chaser.ai.models` 中预置了默认模型
- 确认 `base-url`、`model-name` 和 `api-key` 填写正确
- 如果模型服务不兼容 OpenAI Chat Completions，前端会无法正常调用
- 数据优化时，如果当前组件使用的是 `excel` 或其他未开放的数据源，会被直接判定为不支持

### 7. 迁移失败

处理方式：

- 查看 `logs/error.log`
- 确认数据库账号密码正确
- 确认迁移脚本可执行
- 必要时先把 `light-chaser.migration.enable` 设为 `false` 启动，排查数据库状态

## 资源访问说明

服务会继续提供以下运行时资源路径：

- `/static/images`
- `/static/covers`

如果你调整了 `light-chaser.project-resource-path`，这两个路径会跟随新根目录生效。

## 发布包使用建议

解压后的包中只需要保留：

- `lc-server.jar`
- `config/`
- `data/`
- `logs/`

其中：

- `lc-server.jar` 负责运行时逻辑
- `config/` 负责环境差异
- `data/` 负责持久化资源
- `logs/` 负责排查问题