安装包与启动脚本

最后更新: 2026/10/3

发行包的目录结构、start / install 脚本的用法、JVM 内存与环境变量、注册为系统服务的方法（Linux、macOS、Windows）。

概述

发行包是一个 zip，解压后所有文件平级放置。产品 jar 内已包含前端页面，不需要另外部署静态资源。安装与运维通过包内脚本完成，没有图形化安装器。

发行包内容

文件	说明
`sight-report.jar` / `sight-wall.jar`	主程序（按产品不同）
`start.sh` / `start.bat`	前台启动脚本（Linux、macOS / Windows）
`install.sh` / `install.bat`	注册为系统服务（Linux 用 systemd，macOS 用 launchd）/ 注册 Windows 开机自启任务
`README.txt`	启动说明

Sight Report 可选携带 data/models/（内置语义检索模型，embedding.onnx 与 vocab.txt），随版本更新，为只读文件。示例数据已内置在 jar 中，初始化向导里勾选「导入演示数据」即可导入。

脚本会自动识别目录下的 sight-*.jar，两个产品共用同一套脚本，无需改名。

环境要求

Java 21 及以上的完整运行时（JDK 或 JRE 均可），并已加入 PATH。2.0.61 之前的版本运行期会用到 javac，必须是 JDK。
用 java -version 验证。脚本启动时会检查，低于 21 会报错退出。

发行包的两种启动路径：前台启动与注册为系统服务

前台启动

# Linux / macOS
./start.sh            # 默认 prod 配置
./start.sh dev        # 指定 Spring profile

Windows 运行 start.bat。按 Ctrl+C 停止。

启动脚本会先切换到程序目录（jar 所在目录），再执行 java -jar，因此 data/、logs/ 等相对路径都落在程序目录下。脚本固定附加的 JVM 参数：

参数	作用
`-XX:+ExitOnOutOfMemoryError`	内存溢出时进程直接退出，由服务管理器重启
`-Dfile.encoding=UTF-8`	文件编码
`-Duser.timezone=Asia/Shanghai`	时区

启动前可设置的环境变量

变量	说明	默认值
`SPRING_PROFILES_ACTIVE`	Spring 配置档；命令行参数优先于它	`prod`
`JVM_XMX`	最大堆，如 `8g`。设置后堆大小固定	不设，按可用内存自适应
`JVM_XMS`	初始堆，仅在设置了 `JVM_XMX` 时生效	与 `JVM_XMX` 相同
`JVM_RAM_PCT`	未设 `JVM_XMX` 时，最大堆占可用内存的百分比	`75`
`JVM_OPTS`	追加的 JVM 参数，如 `-Dkey=value`	空

提示：README 建议生产环境显式设置 JVM_XMX=8g 或更高。总内存小于 2GB 且未设置 JVM_XMX 时，start.sh 会输出提示。

注册为系统服务

服务名取自 jar 文件名：sight-report.jar 对应服务 sight-report，sight-wall.jar 对应 sight-wall。

Linux（systemd，需 root）

进入程序目录。
执行 sudo ./install.sh。脚本会写入 /etc/systemd/system/sight-report.service，执行 daemon-reload，设置开机自启并启动。
用 systemctl status sight-report 查看状态，用 journalctl -u sight-report -f 跟踪日志。

install.sh 的用法：

命令	说明
`sudo ./install.sh` 或 `sudo ./install.sh install`	安装并启动，profile 默认为 `prod`
`sudo ./install.sh install dev`	指定 profile
`sudo ./install.sh status`	查看状态
`sudo ./install.sh uninstall`	卸载服务，`data/`、`logs/` 保留

生成的 unit 中，服务以调用 sudo 的用户身份运行（SUDO_USER，没有则为 root），工作目录为程序目录，启动命令为 start.sh <profile>，并设置 Restart=on-failure、RestartSec=5、TimeoutStopSec=30、SuccessExitStatus=143。

固化 JVM 内存设置：安装时传入变量，脚本会写入 unit 的 Environment=。

JVM_XMX=8g sudo -E ./install.sh

注意：sudo 默认会清除环境变量。上面示例用 -E 保留；也可以写成 sudo JVM_XMX=8g ./install.sh，或安装后手工在 unit 中加一行 Environment=JVM_XMX=8g，再执行 systemctl daemon-reload && systemctl restart sight-report。

macOS（launchd，需 root）

sudo ./install.sh 会写入 /Library/LaunchDaemons/com.sight.sight-report.plist 并加载，KeepAlive 为开启。日志在 logs/launchd.out.log 与 logs/launchd.err.log。status、uninstall 用法同上。

Windows

以管理员身份运行 cmd：

install.bat             注册开机自启并启动
install.bat status      查看
install.bat uninstall   卸载，data\、logs\ 保留

Windows 版通过 schtasks 注册一个以 SYSTEM 身份、开机触发的计划任务，任务名取自 jar 名（如 sight-report）。它是「开机启动」任务，不包含 Linux 版的崩溃自动重启配置。

目录与日志

运行后，程序目录下自动生成：

目录	内容
`data/`	本地数据、配置、字体、驱动、插件、缓存、备份等，详见配置项参考
`logs/`	运行日志，文件名含 `info` 与 `error`

注意：data/ 里保存着数据库连接配置、内置数据库文件和备份包。升级时只替换 jar，不要用 rsync --delete、先删目录再解压、或 FTP 的「镜像同步」模式覆盖程序目录。见升级与变更管理。