实例管理
本章介绍实例的日常管理：启停、修改数据库连接与访问端口、重置管理员，以及三种管理入口的使用。
一台机器可运行多个相互独立的实例，各自拥有独立的数据库、端口与数据。管理这些实例的工具称为 Setup 管理器。
1. Setup 管理器
Setup 管理器是运行在本机的轻量管理服务，负责该机器上全部实例的生命周期。
| 特性 | 说明 |
|---|---|
| 仅本机可访问 | 只监听回环地址与一个随机端口，其他机器无法连入，通过一次性令牌鉴权 |
| 空闲自动退出 | 30 分钟无操作即自动关闭。再次使用时重新启动即可，实例本身不受影响——实例是各自独立的后台服务，不依赖管理器在线 |
| 同机唯一 | 不会重复启动 |
1.1 三个入口，功能一致
| 入口 | 适用场景 | 启动方式 |
|---|---|---|
| 网页 | 有图形界面的环境 | kimpoctl setup open |
| 终端界面 | 无图形界面的服务器 | kimpoctl setup tui |
| 命令行 | 脚本与自动化运维 | kimpoctl instance ... |
命令行工具的路径见各平台安装章节。macOS 已软链至 /usr/local/bin/kimpoctl；Windows 与 Linux 位于主程序目录的 bin/ 下。
1.2 管理器的启停
bash
kimpoctl setup start # 确保管理器已运行，输出进程号与地址
kimpoctl setup open # 启动并在浏览器打开管理页（无图形界面时自动转为终端界面）
kimpoctl setup status # 查看管理器状态（加 --json 输出机器可读格式）
kimpoctl setup stop # 停止管理器⚠️ 网页管理页右上角的「退出 Setup」会停止管理器，不只是关闭页面。只是暂时离开时直接关闭浏览器即可；确需结束管理时再使用该按钮。终端界面在退出时会询问「仅退出」还是「退出并停止管理器」，区分更明确。
2. 实例列表
打开管理页后，已有实例以卡片形式列出，每张显示：
| 信息 | 说明 |
|---|---|
| 显示名与实例标识 | |
| 状态 | 运行中、已停止、目录缺失 |
| 访问地址 | 形如 http://127.0.0.1:8080，运行中才显示 |
| 数据库摘要 | 主机:端口/库名（用户名），不显示密码 |
关于「目录缺失」状态：实例目录被移动或删除时，卡片显示该状态并提示原路径。此类实例无法启停或修改配置，需先将目录还原至原位置，或删除后重建。系统通过指针索引记录各实例目录的位置。
3. 常用操作
3.1 新建实例
列表页右上角「新建实例」进入向导。建立第二个及以后的实例与首次建立使用同一套四步向导，只需指定不同的端口与数据库。各步骤的字段与校验见安装与实例初始化。
3.2 启动与停止
卡片上的「启动」「停止」直接切换运行状态，过程无进度页。停止只是停掉该实例的后台服务，不改动任何数据。
3.3 修改数据库连接
卡片「数据库设置」可修改主机、端口、库名、用户名、密码。
| 要点 | 说明 |
|---|---|
| 保存会重启实例 | 页面顶部提示「保存并重启会短暂停止该实例」 |
| 密码留空表示不修改 | 仅在需要更换时填入新值 |
| 必须先测试连接 | 测试不通过无法保存 |
| 运行中的实例需二次确认 | 保存时会再次确认（将重启实例） |
⚠️ 当前仅 MySQL 实际可用。 新建向导中虽然可以看到 PostgreSQL 选项，但选中后无法通过下一步的连接测试。该选项为将来预留。
3.4 修改访问端口
卡片「访问设置」中只有一项：HTTP 端口。保存后同样会重启实例。绑定地址固定为 0.0.0.0，无需设置。
3.5 重置管理员
当某个实例的 admin 账号被改名、禁用或遗忘密码而无法登录控制台时，使用卡片上的「重置管理员」恢复。
执行内容：将该实例的默认管理员重置为登录名 admin、一个新的随机初始密码，并将其启用、解锁、恢复超级管理员角色。部门归属与其他角色不受影响。
执行方式：点击后二次确认，确认即立即生效。该操作直接作用于实例数据库，不经过实例服务，因此实例处于停止状态时同样可以执行。
🔴 新密码通过弹窗一次性展示，关闭后不再显示，请当场记录。 界面提示为「该密码仅显示这一次，请立即保存；登录后必须修改密码」。
重置管理员属应急手段，完成后应立即登录并修改该密码。
3.6 操作进度
新建实例、修改数据库或端口等操作会进入进度页，按阶段依次推进：
校验 → 写入配置 → 初始化数据库 → 安装组件 → 注册服务 → 启动 → 健康检查| 结果 | 界面表现 |
|---|---|
| 成功 | 显示访问地址，可直接打开或返回列表 |
| 失败 | 显示失败所处阶段与日志文件（operations.log）位置，并提供「返回修改」。失败的实例会被彻底清理，不留半成品 |
4. 命令行管理
适用于脚本化运维，各子命令均可加 --json 输出机器可读结果。
bash
kimpoctl instance list # 列出全部实例（标识/名称/状态/地址/数据库摘要）
kimpoctl instance show <标识> # 查看实例详情（密码不会输出）
kimpoctl instance create --name "生产库" \
--db-host 127.0.0.1 --db-port 3306 \
--db-name kimpo_prod --db-user root --db-password-stdin
kimpoctl instance start <标识> # 启动
kimpoctl instance stop <标识> # 停止
kimpoctl instance set-database <标识> --db-host ... --db-password-stdin
kimpoctl instance set-listener <标识> --http-port 8081
kimpoctl instance reset-admin <标识> # 重置默认管理员，输出新登录名与新密码密码不要写在命令行参数中。 使用
--db-password-stdin从标准输入读取，避免明文密码留存于命令历史或进程列表。
create未指定的标识、目录、服务名与端口会自动采用系统建议值；提交前自动执行目录与端口预检以及数据库连通性测试。
5. 终端界面
无图形界面的服务器上使用终端界面完成相同的管理工作：
bash
kimpoctl setup tui列表页按键：↑/↓ 选择、Enter 或 s 启停、d 数据库设置、l 访问设置、a 重置管理员、n 新建、r 刷新、q 退出。
向导内按键：Tab 或 ↑↓ 切换字段、Enter 下一步、Esc 上一步。
退出时询问「仅退出」还是「退出并停止管理器」。
5.1 演练模式
bash
kimpoctl setup tui --dry-run使用内存中的模拟数据运行终端界面，不连接真实服务，也不需要管理员权限。适合在正式操作前熟悉界面。
演练模式预置了若干演示实例，并可触发各类情形以便预先了解：目录路径中包含 exists 演示目录冲突、数据库密码填写 wrong 演示测试失败、端口填写 8080 演示端口占用、库名中包含 fail 演示初始化失败。
与网页端的差异：终端界面的实例目录为手工输入，没有网页端的目录选择器。
6. 相关章节
- 安装与实例初始化 — 建立第一个实例
- 目录结构与随附数据库 — 程序与数据的存放位置
- 初始配置顺序 — 实例建立后的配置步骤
云服务地址与完整版本
Setup Manager「授权」页维护本机所有实例共用的云服务地址。申请试用、授权校验、KimpoAI 及云端能力使用这个地址；实例控制台只读展示。内网部署应先设置可用地址，再完成授权与连通验证。修改会影响同机全部实例，保存后回实例「云服务与 AI」测试连通。
反馈运行问题时同时记录用户菜单中的完整构建版本，不能只记录 beta 或 stable 名称。1.0 之前的数据库不能直接交给 1.0 程序接管，详见版本兼容与更新。