安装 KG OS

本教程面向你选定的 Linux amd64 主机。推荐 Docker Compose + Web 初始化；也提供 Docker 命令和配置文件初始化。已有服务请先核对身份与状态，复用原数据，不按新安装步骤覆盖。

安装顺序：部署与初始化 → 公网 HTTPS → 连接 ChatGPT → AI 制作私人 Plugin → 全局引导词 → 自检与使用。基础 MCP 应用可以独立使用；希望获得七个官方 Skill 与完整使用引导时，继续完成私人 Plugin 安装。

已有实例：先记录实际镜像版本、持久目录、启动配置与公网地址，用第 4 步的只读状态查询确认现状。ready 时沿用原路径从第 6 步验收；其他状态按第 11 步恢复。不要执行新目录、建容器或重新初始化步骤；非本教程布局使用原实例的对应命令。

1. 准备环境

你需要：

• Linux x86_64 主机、可操作 Docker Engine 的账户、Bash、curl、Python 3；Compose 路径另需 Docker Compose 2.30 或更新版本，用于原样读取凭证文件。

• GNU tar、GNU coreutils（含 sha256sum、mv）、可用的 sudo 权限，用于完整备份和保留文件属主；升级前为备份准备足够空间。

• 持久磁盘、可以访问 GHCR 与所选 Embedding 服务的网络。容器内的 localhost 指容器自身；主机或内网模型需要容器可达的真实地址。

• 一个由你管理的域名，例如 kgos.example.com，以及最终根地址 https://kgos.example.com。域名、主机、模型服务和相关费用由你选择。

• OpenAI-compatible Embeddings 服务的 Base URL、模型名、实际输出维度（1–4096）、cosine 或 euclidean 相似度算法，以及服务要求的 API Key；无需认证的服务可留空。

• 目标 ChatGPT 账户或 Workspace 允许添加自定义 MCP、安装并使用 Plugin；制作私人 Plugin 还需要可用的 Plugin Creator。先检查 ChatGPT Plugins 中的入口与 Workspace 权限。缺少能力时由你选择申请管理员开放、改用另一个获准账户，或先完成服务部署；不能把服务成功称作完整安装。

在目标主机确认环境：

uname -m
docker version
docker compose version

预期架构为 x86_64，Docker 输出包含 Server；仅 Docker 命令路径可跳过 Compose 检查。当前发行不提供原生 arm64 镜像。本教程不覆盖模拟运行或替你选择云主机。

版本与镜像

适用版本：KG OS v0.3.0。 镜像与官方 Plugin 来自 正式 Release，命令固定版本和不可变 digest：

ghcr.io/byiyli/kgos:v0.3.0@sha256:f5a3a9c7a343bd073584f82cb4abac25aab916455509f8d9474c188f919e654b

该镜像仅支持 linux/amd64，默认端口 3777，运行身份 10001:10001。容器 /workspace 对应你的持久目录，实例配置与数据位于其下的 .kgos。官方当前不提供 :latest 浮动标签。已有实例先按升级流程核对兼容性，不直接套用新安装步骤。

通过页面版本菜单查看各个正式发布版本的完整手册；切换语言时保持所选版本。本版中英文手册、AI 安装指南和官方 Plugin均适用于 KG OS v0.3.0。新版本发布不会覆盖本版正文；升级前查看目标版本说明。官方 Plugin 包用于取得 Skill 与资源，AI 安装流程以本版配套指南为准。

建立独立安装目录

以下命令用于全新安装。先检查项目目录、容器名、网络名和卷名是否已被使用：

ls -ld "$HOME/kgos"
docker ps -a --format '{{.Names}}'
docker network ls --format '{{.Name}}'
docker volume ls --format '{{.Name}}'
ss -ltn

新安装时，目录不存在导致 ls 报错是正常的。若已有 ~/kgos、kgos、kgos-caddy、kgos-net、kgos-caddy-data、kgos-caddy-config 或端口 3777 被占用，先确认归属。选择复用原安装或为新安装更换整套名称和端口，不能删除或接管未知资源。若主机没有 ss，使用其网络管理工具确认端口。

确认上述名称空闲后，在同一个终端中依次执行；任一命令失败先处理，不继续粘贴后续命令：

(
  set -eu
  umask 077
  mkdir "$HOME/kgos"
  cd "$HOME/kgos"
  sudo install -d -m 0700 -o 10001 -g 10001 "$PWD/workspace" "$PWD/workspace/.kgos"
  install -m 0600 /dev/null embedding.env
  docker network create kgos-net
  docker pull ghcr.io/byiyli/kgos:v0.3.0@sha256:f5a3a9c7a343bd073584f82cb4abac25aab916455509f8d9474c188f919e654b
)

准备命令在独立子 Shell 中遇错即停；已有目录不会继续执行权限或文件操作。中断后先检查已经创建的目录、网络和已拉取的镜像，仅补齐确认缺失的步骤，不整段重跑，也不删除已生成的数据。全部成功后，后续命令均在以下工作目录与私有文件权限下执行：

cd "$HOME/kgos"
umask 077

workspace 只在这次新建的目录上设置权限；不要对已有数据目录递归改属主。embedding.env 是仅本机账户可读写的凭证文件，Web 路径保持为空。

2. 选择初始化方式

只选一种。已经存在 config.toml、auth.json 或数据库时，先核实是否为旧安装，不要把它当作空目录。

配置文件路径：先准备完整配置

在 ~/kgos 创建 config.toml，用你的域名、服务和模型替换示例值。下列 OpenAI 地址与模型只演示字段关系，不表示你已选择该供应商；模型输出必须实际为配置维度。

[server]
public_origin = "https://kgos.example.com"

[cache]
path = "cache/openai-compatible.db"
max_size_mb = 4096

[sqlite]
extensions = []

[fulltext]
analyzer = "jieba"

[embedding]
base_url = "https://api.openai.com/v1"
model = "text-embedding-3-small"
dimensions = 1536
similarity = "cosine"
api_key_env = "KGOS_EMBEDDING_API_KEY"

• public_origin 是最终公网 HTTPS 根地址，不含 /mcp、其他路径、查询参数或片段；填写它不会自动配置域名或证书。
• cache.path 相对 .kgos 解析，max_size_mb 是正整数；示例使用 4096 MiB 的向量缓存预算，并不预占等量磁盘。cache、fulltext 和 embedding 字段必须完整，不能省略来表示默认或关闭。
• sqlite.extensions=[] 不需要填写镜像已内置的官方扩展。jieba 是内置全文分析器。
• Base URL 不附加 /embeddings；实际请求使用 Base URL 加 /embeddings。示例不会发送 dimensions 参数，维度应匹配模型实际返回值。
• 需要认证时，在本机编辑器中打开 embedding.env，填写下列格式；将占位内容替换成真实值，不加引号。不要将密钥写进 TOML、命令历史、Git 或聊天。

KGOS_EMBEDDING_API_KEY=replace-with-your-provider-key

无需认证时，TOML 改为 api_key_env = ""，并保持 embedding.env 为空。不要设置保留变量 KGOS_WEB_EMBEDDING_API_KEY，它只供 Web Setup 内部使用。

保存后将配置安装到实例目录，确保只有运行身份能读写：

chmod 600 config.toml embedding.env
sudo install -m 0600 -o 10001 -g 10001 config.toml workspace/.kgos/config.toml

继续第 3 步。完整合法的配置会在 daemon 启动时触发自动初始化；不需要再启动一个初始化容器或第二个 daemon。

3. 选择启动方式

两种方式共享 workspace、embedding.env 与 kgos-net。二选一，不要同时创建两个服务。端口只绑定主机 loopback，初始化前不对公网开放。

Docker Compose（推荐）

在 ~/kgos/compose.yaml 保存完整配置：

services:
  kgos:
    image: ghcr.io/byiyli/kgos:v0.3.0@sha256:f5a3a9c7a343bd073584f82cb4abac25aab916455509f8d9474c188f919e654b
    platform: linux/amd64
    container_name: kgos
    user: "10001:10001"
    restart: unless-stopped
    ports:
      - "127.0.0.1:3777:3777"
    volumes:
      - ./workspace:/workspace
    env_file:
      - path: ./embedding.env
        format: raw
    networks:
      kgos:
        aliases:
          - kgos
networks:
  kgos:
    external: true
    name: kgos-net

docker compose -f compose.yaml config --quiet
docker compose -f compose.yaml up -d
docker compose -f compose.yaml logs --tail 80 kgos

config --quiet 仅验证结构，不输出展开后的凭证。预期容器保持运行，无权限或初始化失败日志。随后进入第 4 步。

Docker 命令

此路径不依赖 Compose。在 ~/kgos 执行：

docker run -d \
  --name kgos \
  --platform linux/amd64 \
  --user 10001:10001 \
  --restart unless-stopped \
  --network kgos-net --network-alias kgos \
  -p 127.0.0.1:3777:3777 \
  --mount type=bind,src="$PWD/workspace",dst=/workspace \
  --env-file "$PWD/embedding.env" \
  ghcr.io/byiyli/kgos:v0.3.0@sha256:f5a3a9c7a343bd073584f82cb4abac25aab916455509f8d9474c188f919e654b
docker logs --tail 80 kgos

预期容器保持运行，无权限或初始化失败日志。若名称已存在，检查现状，不重复运行创建命令。

4. 完成初始化

先在服务主机查询：

curl --fail --silent --show-error http://127.0.0.1:3777/api/v1/setup/status

• Web 路径预期 state="setup_required"，接着使用下面的向导。
• 配置文件路径预期先 initializing，最终 ready；跳到配置文件路径的检查。
• 返回 error 时读公开 message 和容器日志，按文末恢复；请求受理或容器运行不等于完成。

Web 路径：五步初始化

在服务主机的浏览器打开 http://127.0.0.1:3777/setup。若服务在远程主机，在你的电脑另开终端建立 SSH 转发，将用户名和主机替换为你已有的 SSH 连接：

ssh -N -L 13777:127.0.0.1:3777 your-user@your-server

保持 SSH 终端运行，在本机浏览器打开 http://127.0.0.1:13777/setup。浏览器不需要直接访问服务器 3777 公网端口。

依次完成页面的五步：

1. 欢迎：确认这是你要初始化的独立实例。
2. 公网地址：把 loopback 预填值改为最终 https://kgos.example.com，替换成你实际的域名。不是浏览器当前的 SSH 转发地址。
3. 向量模型：填写你选定的 Base URL、模型、实际维度、算法及 API Key；无需认证时留空。点击连接测试，必须实际请求成功且返回维度匹配后继续。页面预填供应商只是示例，不代表你的选择。测试地址必须从容器可达；向导会拒绝 loopback、链路本地及特殊保留地址。
4. 管理员凭证：生成管理员 Token，立即保存到你自己的密码管理器。同一浏览器已有有效 Session 时会自动恢复；向导不提供手动输入旧 Token 的入口。Token 只在可信本地或 SSH 转发页面输入，不粘贴到聊天。
5. 确认并初始化：核对配置后提交，等待状态变为 ready；失败时保留配置与数据，按文末诊断原因后重启原容器恢复，不重新建库。

Web 会保存完整配置；Embedding Key 单独保存在私有文件中，不写入 TOML。未提交配置且浏览器 Session 已丢失时，由你决定是否通过向导重新生成 Token；这会使旧 Token 和 Session 失效，必须重新安全保存。配置已提交后，不再提供此操作；出现 error 应保留配置和 auth.json，查明原因后重启原容器恢复。

继续条件：真实 Embedding 测试通过、Token 已安全保存、setup/status 为 ready。满足后进入第 5 步。

配置文件路径：管理员凭证与真实模型检查

等待 state="ready"。系统会生成并保留 .kgos/auth.json 中的管理员 Token；通过可信终端把它复制到仅你可读的文件，在本机编辑器查看并保存到密码管理器，不在终端回显：

sudo install -m 0600 -o "$(id -u)" -g "$(id -g)" workspace/.kgos/auth.json admin-credential.json

用该 Token 在上述本地或 SSH 转发入口登录 Web。ready 说明运行时与数据库已初始化，不证明远端模型可用。

执行下面的一次性检查。它会额外拉取 Python 官方镜像，仅短暂共享 KG OS 的网络，将实例目录以只读方式挂载，只读取配置及所需的模型凭证并发送一个 Embedding 请求；不创建本体、知识、分支或 Commit。配置文件路径从你的 embedding.env 读取凭证；Web 路径仅在配置指定保留变量时读取实例私有模型凭证文件，响应正文和密钥不输出。请求可能产生供应商的一次模型调用费用。

docker run --rm -i \
  --network container:kgos \
  --env-file "$PWD/embedding.env" \
  --mount type=bind,src="$PWD/workspace/.kgos",dst=/instance,readonly \
  python:3.13-alpine python - <<'PY'
import json, math, os, pathlib, sys, tomllib, urllib.request
class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None
try:
    with open('/instance/config.toml', 'rb') as f:
        cfg = tomllib.load(f)['embedding']
    headers = {'Content-Type': 'application/json'}
    if cfg['api_key_env']:
        key = (pathlib.Path('/instance/embedding-api-key').read_text()
               if cfg['api_key_env'] == 'KGOS_WEB_EMBEDDING_API_KEY'
               else os.environ.get(cfg['api_key_env'], ''))
        if not key:
            raise ValueError('missing credential')
        headers['Authorization'] = 'Bearer ' + key
    body = json.dumps({'model': cfg['model'], 'input': 'KG OS installation check',
                       'encoding_format': 'float'}).encode()
    req = urllib.request.Request(cfg['base_url'].rstrip('/') + '/embeddings',
                                 data=body, headers=headers, method='POST')
    with urllib.request.build_opener(NoRedirect).open(req, timeout=30) as response:
        result = json.load(response)
    vector = result['data'][0]['embedding']
    assert len(vector) == cfg['dimensions']
    assert all(type(v) in (int, float) and math.isfinite(v) for v in vector)
    assert any(v != 0 for v in vector)
    print('Embedding check passed:', len(vector), 'dimensions')
except Exception:
    print('Embedding check failed; check URL, model, dimensions, credential and network.', file=sys.stderr)
    sys.exit(1)
PY

预期输出 Embedding check passed 和你配置的维度。失败先修复既定服务、网络或凭证；初始化后的模型、维度、相似度和全文分析器不能按新安装示例直接更换，确需变更时先取得适用的迁移方案，由你选择。凭证按文末的受控更新步骤处理；若改环境文件，须重新创建本教程的服务容器以载入环境，保留同一 workspace 挂载，不删除数据。Compose 可用 docker compose -f compose.yaml up -d --force-recreate kgos；Docker 路径先停止并删除本教程刚创建的容器再用原创建命令启动，不能删除卷或目录。完成同网络检查后再开放公网。此检查也支持 Web 初始化后的原配置，可在升级时复用；不需要重新打开 Setup 或生成凭证。

5. 配置公网 HTTPS

只有第 4 步通过后才开放公网入口。已有可信 HTTPS 反向代理可以复用：将请求转发到本实例，保留 Host/协议、支持 MCP 流式响应，确保外部根地址与 public_origin 一致。

以下标准方案使用 Caddy 自动 HTTPS：

1. 将你域名的 A 记录指向这台主机公网 IPv4；若配置 AAAA，IPv6 也必须实际可达。
2. 在主机防火墙、云安全组和必要的路由/NAT 中允许外部 TCP 80、443 到达该主机，并确认未被其他服务占用。保持 KG OS 3777 只在 loopback 发布。
3. 主机允许 HTTPS 出站访问证书颁发服务；填写域名不等于已有证书。

在 ~/kgos/Caddyfile 保存，替换为你的真实域名：

kgos.example.com {
    reverse_proxy kgos:3777 {
        flush_interval -1
    }
}

Caddy 与 KG OS 使用同一个 kgos-net 网络；kgos 是容器网络别名。以下两种方式与第 3 步对应，选原来的路径。

Compose 路径的 HTTPS

在 compose.https.yaml 保存：

services:
  caddy:
    image: caddy:2.11.7-alpine
    container_name: kgos-caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - kgos
volumes:
  caddy_data:
    name: kgos-caddy-data
  caddy_config:
    name: kgos-caddy-config

docker compose -f compose.yaml -f compose.https.yaml config --quiet
docker compose -f compose.yaml -f compose.https.yaml run --rm --no-deps caddy caddy validate --config /etc/caddy/Caddyfile
docker compose -f compose.yaml -f compose.https.yaml up -d caddy
docker logs --tail 80 kgos-caddy

Docker 命令路径的 HTTPS

docker volume create kgos-caddy-data
docker volume create kgos-caddy-config
docker run --rm \
  --mount type=bind,src="$PWD/Caddyfile",dst=/etc/caddy/Caddyfile,readonly \
  caddy:2.11.7-alpine caddy validate --config /etc/caddy/Caddyfile
docker run -d \
  --name kgos-caddy \
  --restart unless-stopped \
  --network kgos-net \
  -p 80:80 -p 443:443 \
  --mount type=bind,src="$PWD/Caddyfile",dst=/etc/caddy/Caddyfile,readonly \
  --mount type=volume,src=kgos-caddy-data,dst=/data \
  --mount type=volume,src=kgos-caddy-config,dst=/config \
  caddy:2.11.7-alpine
docker logs --tail 80 kgos-caddy

首次启动会申请证书；成功前不要继续。Caddy 的 /data 和 /config 是持久卷，重建代理时继续使用，不清理证书存储。证书申请失败时按常见问题处理，成功后再继续。

6. 验收服务

HTTPS、Web 与认证

在能够访问公网的客户端执行，替换示例域名；不要使用 -k 跳过证书检查：

curl --fail --silent --show-error https://kgos.example.com/api/v1/setup/status
curl --silent --show-error -D - -o /dev/null https://kgos.example.com/mcp
curl --fail --silent --show-error https://kgos.example.com/.well-known/oauth-authorization-server
curl --fail --silent --show-error https://kgos.example.com/.well-known/oauth-protected-resource/mcp

验收结果应同时满足：

• HTTPS 证书可信，公开 setup/status 返回 ready，并且 MCP 路径为 /mcp。
• 匿名 /mcp 返回 401，WWW-Authenticate 指向正确的 OAuth 资源元数据；匿名拒绝是预期。
• OAuth 元数据的 issuer、授权/Token 地址和资源地址均指向你填写的公网根地址。
• 浏览器打开 https://kgos.example.com，使用你保存的管理员 Token 正常登录；确认进入正确实例并可读取现有版本和知识视图。空知识库允许通过，不创建测试业务数据。

这只是服务及公开接入验收，不等于 ChatGPT 已连接或 MCP 工具调用已通过。

重启与持久化

确认此时没有其他客户端写入。下面脚本只读调用当前版本与一致性接口，仅保留 State 标识、一致性及数据/Token 摘要，不落盘完整 State 数据或凭证；记录只在本机比较，不用于公开分享。第 1 步的 umask 077 使这些文件仅当前账户可读写。首次使用前创建 acceptance.py：

import hashlib, json, pathlib, urllib.request
root = pathlib.Path('workspace/.kgos')
token = json.loads((root / 'auth.json').read_text())['token']
def call(path, body):
    request = urllib.request.Request('http://127.0.0.1:3777/api/v1/' + path,
        data=json.dumps(body).encode(), method='POST',
        headers={'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json'})
    with urllib.request.urlopen(request, timeout=30) as response:
        return json.load(response)
overview = call('evolution/overview', {})
state = call('evolution/get', {'state': overview['state']})
assert state['state'] == overview['state']
assert state['consistency']['status'] == 'valid'
assert state['consistency']['issues'] == []
data_hash = hashlib.sha256(json.dumps(state['data'], sort_keys=True,
    separators=(',', ':')).encode()).hexdigest()
print(json.dumps({'overview': overview, 'state': state['state'],
    'consistency': state['consistency'], 'hasData': state['hasData'],
    'stateDataFingerprint': data_hash,
    'credentialFingerprint': hashlib.sha256(token.encode()).hexdigest()}, sort_keys=True))

在服务主机执行，保存重启前记录：

sudo python3 acceptance.py > acceptance-before.json

按原启动方式只重启本教程的 KG OS 容器：

Compose 路径：

docker compose -f compose.yaml restart kgos

Docker 命令路径：

docker restart kgos

只执行所选路径的命令。重新查询 setup/status，待 ready 后执行：

sudo python3 acceptance.py > acceptance-after.json
diff -u acceptance-before.json acceptance-after.json

预期无差异：默认分支、不可变 State、State 数据及管理员身份保持一致。再次用原 Token 登录并读取原有内容。非空库还应在 Web 核对原有内容；空库无需为了验收创建知识。并发写入可能正常改变记录，应先排除它，不能据此重置数据。

服务安装完成条件：初始化 ready、真实 Embedding 验证通过、HTTPS 与认证正确、重启后身份/State/已有数据保持。任何一项失败或不可观察，保留已完成部分并继续处理对应缺项。

7. 连接 ChatGPT 并验收

服务验收通过后，在你选定的账户或 Workspace 操作。这里先创建可使用 MCP 的基础应用；ChatGPT 会将它显示为 Plugin，它尚不包含七个官方 Skill。已有指向正确实例的可用应用，直接复用并进入只读验收。

添加基础 MCP 应用

按 OpenAI 官方连接流程操作，界面名称以当前账户实际显示为准：

1. 打开 ChatGPT Plugins，先确认当前账户与 Workspace。
2. 选择 ＋ → Add custom MCP server，填写可识别的名称（例如“KG OS 基础连接”）和用途说明。
3. 在 Connection 选择公网地址，填入 https://你的域名/mcp，不能只填根地址或 /setup。
4. 选择 OAuth。KG OS 使用 ChatGPT CIMD 身份与 PKCE，不需要自建 OAuth client ID 或 client secret。若界面要求填写它们，不填管理员 Token，先核对所选认证方式与平台能力。
5. 阅读授权风险与工具权限，仅在接受后勾选 I understand and want to continue，再选择 Create as a plugin。按页面提示完成 OAuth；确认跳转域名是你自己的 KG OS，必要时在该站点用管理员 Token 登录，核对并同意 ChatGPT 的连接请求。
6. 检查服务实际发现的工具和名称，安装生成的基础 Plugin。新建会话，在输入框键入 @ 并选择它。

KG OS 当前连接权限包含读写；安装验收只执行只读调用，后续写入仍需你的授权。管理员 Token 只在自己的可信 KG OS Web 页面输入，不能放进 ChatGPT 的 client secret、安装提示词或聊天。服务重启后 OAuth Access/Refresh Token 会失效；在原连接重新授权即可，管理员身份和知识库仍保留。不要因此删除应用或重新初始化。

在目标 ChatGPT 会话实际验证

选中基础 Plugin 后，发送以下只读请求；先将“目标服务”对应到你刚创建或复用的连接，不能因两个连接有相同 State 就认定它们是同一物理实例：

请只读检查当前会话选中的 KG OS 应用，不写入数据。

1. 确认连接指向我指定的公网服务和账户。
2. 用 kgos_docs 读取 guides/reading.md、guides/evolution.md 及当前 SDK 签名。
3. 调用 evolution.overview 解析不可变 State，再用该 State 调用 evolution.get。
4. 确认返回同一 State、consistency.status="valid"、consistency.issues=[]。
5. 用同一 State 调用 ontology.read，核实业务读取成功，不能只看外层工具返回成功。
   列出应用与连接、实际 State、检查结果、失败和未知项。空知识库允许通过；不创建模型、知识、分支或 Commit。

继续条件：文档和业务读取真实成功、连接指向选定服务、同一 State 的一致性正常且 Ontology 可读。工具列表出现或 OAuth 页面成功不能单独代替验收。空知识库允许通过；失败先按恢复表处理，保留已连接应用，成功后再进入下一步。

8. 制作私人 Plugin、配置引导词并自检

在 ChatGPT Plugins 找到并安装 Plugin Creator；已可用时直接复用。在安装会话中启用它与已通过验收的基础 KG OS 应用；若当前界面无法同时选中，使用会话可用的应用选择或工具入口。找不到 Plugin Creator 时先核对账户与 Workspace 权限，不改动现有连接。复制下面的请求，替换方括号；没有旧私人 Plugin 时填写“无”，不确定时说明未知，不提供凭证：

请按照官方 KG OS 私人 Plugin 安装手册协助安装：
https://kgos.sites.y2l.top/install/v0.3.0/INSTALL.md

已验证的 ChatGPT KG OS 应用：[应用名称]
公网服务：https://[我的域名]
目标 ChatGPT 账户/Workspace：[目标]
已有私人 Plugin：[名称与版本；没有则填“无”]
使用需求与需要保留的定制：[说明]

复用这个应用和连接，不重新部署或初始化服务。
检查实际服务、官方发行物及旧 Plugin/定制，给出具体方案，经我确认后新建并安装带版本号的私人 Plugin，保留七个官方 Skill。迁移我的定制，冲突由我选择。新版本验收前保留旧 Plugin 和共享连接，未获授权的清理由我决定。
提供完整官方全局引导词与 ChatGPT 配置步骤，最后完成安装自检。不要让我在聊天中提供凭证，已授权步骤不要重复确认。

接下来由 AI 按唯一 INSTALL.md协助完成：

1. 确认方案：核对服务与同版官方资源；如有旧私人 Plugin，读取旧版内容并与旧官方基线比较，列出定制迁移与冲突。你选择目标、迁移内容、权限与安装范围，确认具体方案后执行。已授权步骤不重复确认。
2. 创建并安装新版本：每次新建名称带官方版本号的私人 Plugin，同版重做增加修订号；复用基础应用的真实连接，保留七个官方 Skill 与资源。旧 Plugin 先保留，发生冲突由你选择，不原地覆盖。
3. 配置全局引导词：AI 给出完整官方 Global AI Guidance v1。按 ChatGPT 个性化设置打开 Settings → Personalization → Custom instructions，查看现有内容，由你选择追加、合并或替换冲突部分并保存；不静默覆盖原指令。字段长度不足时保留官方正文，先决定如何精简已有内容，不将删节版声称为完整官方引导词。
4. 新会话自检：安装新 Plugin，确认其启用后新建会话并通过 @ 选中；不在会话中重新粘贴引导词作为“已生效”的证明。发送：

使用已安装的 kgos-doctor Skill，只做安装相关 D1–D3 自检：全局引导词、选定 KG OS MCP 连接与知识库、七个官方 Skill。复用适用的已有证据，分别报告配置/安装状态、真实调用、版本、资源可用性及不可观测项。空知识库允许通过；不写入知识、不创建分支或 Commit、不配置维护任务、不卸载任何内容。

AI 应分别列出服务和应用、私人 Plugin 版本、七个官方 Skill 与引用资源、引导词保存和可观察行为，以及旧定制迁移结果。七个 Skill 为 Ontology、Knowledge、Retrieval、Branch、Maintenance、VLog 规范和 Doctor，实际资源以所选版本发行包为准。

完整安装条件：服务与 ChatGPT 真实读取通过，所选版本私人 Plugin 已安装，七个 Skill 及必要资源齐备可用，引导词完整保存，相关 D1–D3 没有已确认的阻塞缺项。隐藏的宿主加载来源或自动触发轨迹可以标为不可观测，不能据此无限检查；“已安装”“实际可用”“观察到使用”分别记录。知识质量、维护调度与写入业务数据不属于安装条件。你明确选择只使用基础 MCP 应用时，以该范围交付，不声称已安装私人 Plugin。

新 Plugin 验收后，你可选择卸载旧私人 Plugin；不删除仍被使用的基础应用或共享 MCP 连接。制作、安装或验收失败时保留旧版，从实际失败处继续。

9. 开始使用

新会话选中 KG OS Plugin，按需要提出任务：

• “查看我知识库的入口和分支简介，说明目前有哪些可用内容。”
• “只读查看当前 Ontology，解释已有模型，不创建新模型。”
• “我想把以下资料整理进知识库，请先结合已有模型给出方案，等我确认后再写入。”

空库可以先查看现有结构，再由你授权建模与保存；安装不预建业务模型或测试内容。后续服务版本升级与私人 Plugin 升级分别按下一节处理。

10. 升级与备份恢复

选定目标版本

从 Releases选择正式目标版本，在页面版本菜单打开其完整手册，阅读当前版本到目标版本的兼容性、迁移、停机和恢复要求，取得该版本官方镜像 Tag + digest 及 Plugin 资源。目标版本尚未登记到 KGHub 时，先使用该 Release 提供的配套资料，不使用旧版安装提示词制作新版 Plugin。没有明确支持的升级路径时先停止，向项目确认，不能假定任意跨版本兼容或可降级。

以下命令针对本教程的 ~/kgos、kgos 容器与单一 workspace 布局。先确认当前实际挂载、网络、端口、凭证来源和启动配置；做过定制的实例必须沿用原参数，并将安装目录外的持久目录、凭证和启动文件纳入备份。不要把默认命令覆盖到自定义实例。

记录当前镜像，输入你选定的官方完整镜像引用并预先拉取。输入必须形如 ghcr.io/byiyli/kgos:vX.Y.Z@sha256:…；失败先处理，不进入停机步骤：

cd "$HOME/kgos"
umask 077
docker inspect --format '{{.Config.Image}}' kgos
read -r -p 'Target official image (version@sha256 digest): ' KGOS_TARGET_IMAGE
[[ "$KGOS_TARGET_IMAGE" =~ ^ghcr\.io/byiyli/kgos:v[0-9]+\.[0-9]+\.[0-9]+@sha256:[0-9a-f]{64}$ ]] &&
  docker pull "$KGOS_TARGET_IMAGE"

若恢复到另一个终端，重新设置并核对目标值；不要用空变量或浮动标签继续。代理 Caddy 不随本次 KG OS 服务升级替换，其现有证书卷继续保留。

停止写入并完整备份

暂停 ChatGPT 和其他客户端的写入，等待在途操作结束，先执行 sudo python3 acceptance.py > acceptance-before-upgrade.json 保存第 6 步的只读基线。确认磁盘同时容纳完整备份与运行数据。不要先修改 Compose 镜像或配置，备份必须包含旧版可恢复的启动配置。

Compose 路径：

docker compose -f compose.yaml stop kgos
docker inspect --format '{{.State.Running}}' kgos

Docker 命令路径：

docker stop kgos
docker inspect --format '{{.State.Running}}' kgos

只执行原路径；最后一行必须为 false。若应用由外部管理器自动拉起，先按它原有方式停止，确认不会重新写入，然后继续公共备份步骤：

(
  set -eu
  umask 077
  test "$PWD" = "$HOME/kgos"
  test "$(docker inspect --format '{{.State.Running}}' kgos)" = false
  sudo test -d workspace/.kgos
  install -d -m 0700 "$HOME/kgos-backups"
  backup_dir=$(mktemp -d "$HOME/kgos-backups/pre-upgrade.XXXXXXXX")
  docker inspect kgos > "$backup_dir/container-inspect.private.json"
  docker inspect --format '{{.Config.Image}}' kgos > "$backup_dir/previous-image.txt"
  sudo tar --numeric-owner --acls --xattrs -cpf "$backup_dir/kgos.tar" -C "$HOME" kgos
  sudo chown "$(id -u):$(id -g)" "$backup_dir/kgos.tar"
  chmod 600 "$backup_dir/kgos.tar"
  (cd "$backup_dir" && sha256sum kgos.tar > kgos.tar.sha256 && sha256sum -c kgos.tar.sha256)
  printf '%s\n' "$backup_dir" > .last-upgrade-backup
  printf 'Backup saved: %s\n' "$backup_dir"
)

预期 kgos.tar: OK 并输出新的私有备份目录。归档包含整个安装目录：.kgos 数据库、认证、完整配置、缓存、环境文件、Compose、Caddyfile 及其他现有文件，并保留数字 UID/GID、权限、ACL 和扩展属性。备份放在安装目录外且每次新建，不覆盖旧备份；container-inspect.private.json 可能含密钥，只在本机私有保存，不上传或贴入聊天。

Caddy 的证书卷不在此归档中，本次保持原样；若要迁移整台主机，另行按代理运维方式备份证书卷和外部资源。任何备份、校验或停服检查失败都不替换镜像。镜像已拉取而服务尚未替换时，可以修复备份问题后继续，或启动原容器恢复服务。

按原启动方式替换镜像

Compose：只将原 compose.yaml 中 kgos.image 改为上面选定并已拉取的完整引用，保留其他配置、同一项目目录与全部原挂载。确认新值与目标一致后执行：

(
  set -eu
  test -n "${KGOS_TARGET_IMAGE:-}"
  test "$(docker inspect --format '{{.State.Running}}' kgos)" = false
  backup_dir=$(cat .last-upgrade-backup)
  (cd "$backup_dir" && sha256sum -c kgos.tar.sha256)
  docker compose -f compose.yaml config --quiet
  test "$(docker compose -f compose.yaml config --images)" = "$KGOS_TARGET_IMAGE"
  docker compose -f compose.yaml up -d --no-deps --force-recreate kgos
  docker inspect --format '{{.Config.Image}}' kgos
  docker logs --tail 80 kgos
)

Docker 命令：下列操作保留已停止的旧容器并改名，创建新容器，重新载入同一凭证文件；不会删除 workspace。仅适用于原参数与本教程一致的实例，定制实例应使用已记录的原参数，只更换镜像：

(
  set -eu
  test -n "${KGOS_TARGET_IMAGE:-}"
  [[ "$KGOS_TARGET_IMAGE" =~ ^ghcr\.io/byiyli/kgos:v[0-9]+\.[0-9]+\.[0-9]+@sha256:[0-9a-f]{64}$ ]]
  test "$(docker inspect --format '{{.State.Running}}' kgos)" = false
  backup_dir=$(cat .last-upgrade-backup)
  (cd "$backup_dir" && sha256sum -c kgos.tar.sha256)
  previous_container="kgos-before-upgrade-$(date -u +%Y%m%dT%H%M%SZ)-$RANDOM"
  docker rename kgos "$previous_container"
  printf '%s\n' "$previous_container" > .previous-container
  docker run -d \
    --name kgos \
    --platform linux/amd64 \
    --user 10001:10001 \
    --restart unless-stopped \
    --network kgos-net --network-alias kgos \
    -p 127.0.0.1:3777:3777 \
    --mount type=bind,src="$PWD/workspace",dst=/workspace \
    --env-file "$PWD/embedding.env" \
    "$KGOS_TARGET_IMAGE"
  docker inspect --format '{{.Config.Image}}' kgos
  docker logs --tail 80 kgos
)

若新容器创建失败，旧容器仍以 .previous-container 记录的名称保留；先核实现状再恢复，不重复执行整段。不要同时启动两个访问同一 workspace 的 KG OS 容器，也不要运行 down -v、删卷或初始化命令。

升级验收与 Plugin 升级

查看日志与状态，等待 ready 后执行后两行：

curl --fail --silent --show-error http://127.0.0.1:3777/api/v1/setup/status
sudo python3 acceptance.py > acceptance-upgrade.json
diff -u acceptance-before-upgrade.json acceptance-upgrade.json

核对实际镜像为所选 Tag/digest，按第 6 步检查 HTTPS、原管理员 Token、现有内容、State 和身份。兼容说明允许改变的元数据须按该版本说明判断，不能将差异一概当成功或据此重置。重复第 4 步的同网络真实 Embedding 检查；该检查同时支持 Web 与配置文件初始化，不为验收新增业务数据。模型或凭证问题按原初始化路径诊断，不重新初始化。

重启会使旧 OAuth Token 失效：在原 ChatGPT 连接重新授权，按第 7 步重做只读验收。工具元数据变化时刷新原连接并在新会话检查。服务通过后，切换到升级目标版本的 KGHub 手册，按该版 ChatGPT 与私人 Plugin 步骤读取旧定制、确认迁移方案、创建新版本并验收；交接提示词、INSTALL.md、七个 Skill 和 Plugin 资源都必须对应目标版本，不继续复制本旧版第 8 步的固定版本提示词。再由你选择卸载旧版；不原地替换旧 Plugin，不删除共享连接。

升级失败后恢复

先停止写入和失败的 KG OS 服务，保留失败日志、容器配置、整个失败目录与原备份。镜像回退不等于数据恢复：目标版本可能已经改写数据或配置，不能直接启动旧容器碰运气。

由你选择按目标版本说明修复，或按其支持的恢复方式回到完整旧备份。需要恢复数据时，先将选定的可信备份解包到全新的私有目录进行核对，下面操作不覆盖当前实例：

(
  set -eu
  umask 077
  read -r -p 'Absolute path to the selected pre-upgrade backup: ' backup_dir
  test "${backup_dir#/}" != "$backup_dir"
  (cd "$backup_dir" && sha256sum -c kgos.tar.sha256)
  restore_dir=$(mktemp -d "$HOME/kgos-restore.XXXXXXXX")
  sudo tar --acls --xattrs --same-owner -xpf "$backup_dir/kgos.tar" -C "$restore_dir"
  sudo test -d "$restore_dir/kgos/workspace/.kgos"
  printf 'Restored privately for inspection: %s/kgos\n' "$restore_dir"
)

核对解包目录中的原配置、环境文件与 UID/GID；确认归档是你选定的旧版本、数据完整，且升级前镜像仍可获取。以下恢复命令只适用于本教程标准布局，以及目标版本说明允许恢复整套旧备份的情况。保持所有共享该 workspace 的容器停止；Docker 清单查询失败时不切换目录，不能当作容器不存在。自定义布局须按其原启动合同恢复。命令输入上一步输出的完整恢复路径与选定备份路径；恢复前会比较解包内容与选定归档，防止误用另一份同版本备份。任一检查失败先处理，不重复整段。

Compose 恢复保留原目录、项目名、配置、挂载和外部网络。它先私有保存失败容器的日志与配置，并将整个失败安装目录另名保留；随后 Compose 会替换本教程的失败容器，容器对象本身不作为保留凭据。Caddy 与证书卷不改动：

(
  set -eu
  umask 077
  cd "$HOME"
  read -r -p 'Selected restored directory (.../kgos-restore.XXXXXXXX/kgos): ' restored_path
  read -r -p 'Selected pre-upgrade backup directory: ' backup_dir
  [[ "$restored_path" == "$HOME"/kgos-restore.*/kgos ]]
  test "${backup_dir#/}" != "$backup_dir"
  sudo test -d "$restored_path/workspace/.kgos"
  (cd "$backup_dir" && sha256sum -c kgos.tar.sha256)
  sudo tar --acls --xattrs --compare --file "$backup_dir/kgos.tar" --directory "$(dirname "$restored_path")"
  previous_image=$(cat "$backup_dir/previous-image.txt")
  docker info >/dev/null
  test "$(docker compose -f "$restored_path/compose.yaml" config --images)" = "$previous_image"
  failed_dir=$(mktemp -d "$HOME/kgos-failed.XXXXXXXX")
  container_names=$(docker ps -a --format '{{.Names}}')
  if printf '%s\n' "$container_names" | grep -Fxq kgos; then
    docker stop kgos
    test "$(docker inspect --format '{{.State.Running}}' kgos)" = false
    docker logs kgos > "$failed_dir/container.log.private" 2>&1
    docker inspect kgos > "$failed_dir/container-inspect.private.json"
  fi
  mv -T -- "$HOME/kgos" "$failed_dir/installation"
  test ! -e "$HOME/kgos"
  mv -T -- "$restored_path" "$HOME/kgos"
  cd "$HOME/kgos"
  docker compose -f compose.yaml config --quiet
  docker compose -f compose.yaml up -d --no-deps --force-recreate kgos
  printf 'Failed files retained: %s\n' "$failed_dir"
  docker logs --tail 80 kgos
)

Docker 命令恢复先从当前安装目录读取已记录的升级前容器名，核对其镜像与备份一致；保留旧容器原有环境、挂载和其他参数。失败的新容器改名保留，失败目录另名保留，然后恢复旧容器：

(
  set -eu
  umask 077
  cd "$HOME"
  read -r -p 'Selected restored directory (.../kgos-restore.XXXXXXXX/kgos): ' restored_path
  read -r -p 'Selected pre-upgrade backup directory: ' backup_dir
  [[ "$restored_path" == "$HOME"/kgos-restore.*/kgos ]]
  test "${backup_dir#/}" != "$backup_dir"
  sudo test -d "$restored_path/workspace/.kgos"
  (cd "$backup_dir" && sha256sum -c kgos.tar.sha256)
  sudo tar --acls --xattrs --compare --file "$backup_dir/kgos.tar" --directory "$(dirname "$restored_path")"
  previous_image=$(cat "$backup_dir/previous-image.txt")
  docker info >/dev/null
  previous_container=$(cat "$HOME/kgos/.previous-container")
  [[ "$previous_container" == kgos-before-upgrade-* ]]
  test "$(docker inspect --format '{{.Config.Image}}' "$previous_container")" = "$previous_image"
  docker stop "$previous_container"
  test "$(docker inspect --format '{{.State.Running}}' "$previous_container")" = false
  failed_dir=$(mktemp -d "$HOME/kgos-failed.XXXXXXXX")
  container_names=$(docker ps -a --format '{{.Names}}')
  if printf '%s\n' "$container_names" | grep -Fxq kgos; then
    docker stop kgos
    test "$(docker inspect --format '{{.State.Running}}' kgos)" = false
    docker logs kgos > "$failed_dir/container.log.private" 2>&1
    docker inspect kgos > "$failed_dir/container-inspect.private.json"
    failed_container="kgos-failed-$(date -u +%Y%m%dT%H%M%SZ)-$RANDOM"
    docker rename kgos "$failed_container"
    printf '%s\n' "$failed_container" > "$failed_dir/container-name.txt"
  fi
  mv -T -- "$HOME/kgos" "$failed_dir/installation"
  test ! -e "$HOME/kgos"
  mv -T -- "$restored_path" "$HOME/kgos"
  docker rename "$previous_container" kgos
  docker start kgos
  printf 'Failed files retained: %s\n' "$failed_dir"
  docker logs --tail 80 kgos
)

没有 .previous-container、旧容器丢失或参数与备份不符时，不猜名字、不启动；读取私有备份中的原镜像和原参数，明确恢复方案后重建。目录切换或启动结果未知时先检查原路径、失败目录和容器状态；已移动成功的目录不重复移动，不能覆盖或删除现场。

恢复会放弃备份后发生的修改，必须由你明确选择。恢复后按第 6、7 步重新验收并重新授权 ChatGPT。保留旧镜像、备份和失败现场，直到你确认新版本或恢复版本正常，再决定清理。

11. 常见问题与恢复

受控编辑实例配置

需要修正已保存配置时，编辑实际挂载的实例文件，不是仅修改 ~/kgos/config.toml 模板。先在可信服务终端备份，再用提权编辑器修改必要值：

sudo cp -p --backup=numbered workspace/.kgos/config.toml workspace/.kgos/config.toml.before-edit
sudoedit workspace/.kgos/config.toml
sudo chown 10001:10001 workspace/.kgos/config.toml
sudo chmod 600 workspace/.kgos/config.toml

这里只修正已确认的可变值，例如 public_origin，不递归修改目录。完成后按原路径重启 KG OS，重新检查状态、模型和 OAuth；已有 Token 与数据库继续保留。初始化后的 Embedding 模型、维度、相似度和全文分析器属于已有索引合同，不在这里直接更换；需要适用的迁移说明。

更新模型凭证：保持模型与认证方式不变。配置文件路径在本机编辑 embedding.env，再按第 4 步重新创建原服务容器。Web 初始化且配置使用 KGOS_WEB_EMBEDDING_API_KEY 时，先按原路径停止 KG OS，再执行下列操作；新 Key 只在可信终端的隐藏输入提示中输入，文件不能包含引号或换行：

(
  set -eu
  sudo cp -p --backup=numbered workspace/.kgos/embedding-api-key workspace/.kgos/embedding-api-key.before-edit
  sudo python3 - <<'PY'
import getpass, os, pathlib
path = pathlib.Path('workspace/.kgos/embedding-api-key')
key = getpass.getpass('New Embedding API Key: ')
if not key or len(key.encode()) > 8192 or any(c in key for c in '\r\n\x00'):
    raise SystemExit('Invalid credential; original file retained.')
with path.open('w') as file:
    file.write(key)
    file.flush()
    os.fsync(file.fileno())
os.chown(path, 10001, 10001)
path.chmod(0o600)
PY
)

任一操作失败先保留备份并检查，不启动未确认的文件。成功后启动原容器，重复同网络 Embedding 检查；不重新初始化或改管理员 Token。

需要帮助时提供：镜像版本/digest、选择的两种路径、公开地址、非敏感状态、报错及已完成步骤。不要发送 Token、API Key、auth.json、embedding.env 或完整环境输出。