目录结构与随附数据库

本章说明程序与数据的存放位置，以及随安装部署的数据库的处理方式。

理解主程序目录与实例目录的区分，是升级、备份、卸载时避免误操作的前提。

---

1. 两类目录

程序本体与实例数据分开存放。

1.1 主程序目录（一台机器一份，全部实例共用）

存放可执行程序本身：服务端、命令行工具、内置组件模板、数据库迁移脚本、控制台前端资源。

操作系统	路径
Windows	C:\Program Files\Kimpo
macOS	/Library/Kimpo
Linux	/opt/kimpo

特点：

• 一台机器上的全部实例共用这一份程序；
• 升级时整体替换该目录，不涉及任何实例数据；
• 不存放业务数据，误删后重新安装即可恢复。

命令行工具的位置：主程序目录下的 bin/ 子目录（macOS 与 Linux 经 current 软链接指向当前版本），稳定路径为 <主程序目录>/bin/kimpoctl。macOS 安装时另会软链至 /usr/local/bin/kimpoctl，可在终端直接调用 kimpoctl。

1.2 实例目录（每个实例一份）

存放单个实例的全部数据：数据库连接、配置、证书、业务文件等。

操作系统	默认路径
Windows	C:\ProgramData\Kimpo\instances\<实例标识>
macOS	/Library/Application Support/Kimpo/instances/<实例标识>
Linux	/var/lib/kimpo/instances/<实例标识>

该目录在升级时不会被改动，卸载时默认保留。 业务应用与数据均存放于此。

目录位置可自选，但末级文件夹名必须等于实例标识。

新建实例时可将实例目录指定到其他磁盘（例如数据盘），但根目录的最后一段文件夹名必须与实例标识一致。系统通过一份机器级的指针索引记录各实例根目录的实际位置，不依赖固定路径扫描。

指针索引位置：Windows C:\ProgramData\Kimpo\instances-index；macOS /Library/Application Support/Kimpo/instances-index；Linux /var/lib/kimpo/instances-index。

1.3 实例目录的内容

子路径	内容
instance.json	实例清单（标识、显示名、服务名、创建时间等）
config/config.yaml	实例配置（端口、数据库连接等）
secrets/secrets.json	敏感信息（数据库密码、签名密钥等）
tls/	证书与私钥
data/	实例数据（对象存储、字体等本地文件）
cache/	缓存
runtime/	运行态文件（该实例的组件、启动与配置更新标记等）
backups/config/	配置变更前的自动备份
logs/	该实例的运行日志

这些目录的权限已收紧，日常无需手工修改。

⚠️ 调整实例配置（更换数据库、修改端口等）应通过管理页面或命令行工具执行，不要直接编辑配置文件。 手工修改容易与运行状态不一致。

---

2. 安装状态目录

安装程序与管理器之间通过状态文件交接信息：

操作系统	路径
Windows	C:\ProgramData\Kimpo\setup
macOS	/Library/Application Support/Kimpo/setup
Linux	会话文件在 /run/kimpo/setup（随重启清空）；安装交接文件在 /var/lib/kimpo/setup（持久保留）

其中 install-handoff.json 是连接信息交接文件：安装时若部署了随附数据库，安装程序会将其连接信息（含管理员密码）写入该文件。首次打开新建实例向导时，数据库步骤即读取该文件自动预填连接信息。

⚠️ 该文件含明文密码，确认不再需要后应予删除。

---

3. 随附数据库

系统运行需要 MySQL 8.0。安装包内置一份精简版 MySQL 8.0.46，在满足条件时随安装自动部署。

3.1 部署条件

情形	行为
首次安装	部署随附数据库
升级已安装的机器	不重装、不改动现有数据库
检测到本机已有 MySQL 或 MariaDB 运行（3306 端口被占用或存在相应进程）	自动跳过部署，安装不会因此失败。此时在新建实例向导中手工填写自有数据库的连接信息即可

Windows 与 macOS 的安装界面另提供勾选项显式控制是否部署，详见各平台安装章节。

3.2 管理员密码的位置

随附数据库的管理员密码为随机生成，安装完成后写入一个明文凭据文件：

操作系统	凭据文件
Windows	桌面 mysql_login_info.txt
macOS	当前用户桌面 Kimpo-MySQL-初始密码简报.txt（无法获取桌面路径时位于 /Users/Shared/）
Linux	/root/kimpo-mysql-login-info.txt，安装结束时终端会打印该路径

🔴 该文件包含明文密码，任何能访问这台机器的人都可读取。确认已妥善保存或已修改密码后，应立即删除该文件。系统不会自动清理。

3.3 修改随附数据库的管理员密码

必须完成两个步骤，凭据文件中亦有说明：

1. 使用文件中的初始密码登录数据库，执行改密语句：

   ALTER USER 'root'@'localhost' IDENTIFIED BY '新密码';

2. 打开管理页面，进入对应实例的「数据库设置」，用新密码更新连接信息并保存。

⚠️ 只完成第一步会导致连接失败。 仅在数据库中改了密码而未在管理页面同步更新时，实例仍会使用旧密码连接。两个步骤必须一并完成。

3.4 升级与卸载时的处理

操作	对数据库的影响
升级	不重装、不改动数据库及其中的数据
卸载	默认保留随附数据库的服务、程序、数据目录与全部实例数据库。卸载本系统不会删除业务数据

---

4. 相关章节

• Windows 安装
• macOS 安装
• Linux 安装
• 实例管理 — 实例的启停与配置修改