部署概览

当前线上部署

项	值
服务器	`158.220.110.163` (Ubuntu 24.04 / 16 vCPU / 62GB RAM / 581GB SSD)
反代	Caddy（自动 LE，`flush_interval -1` 对 LLM SSE 友好）
DNS	Cloudflare 灰云（DNS only，A 记录直接指 158）
容器	OrbStack 不适用，用 Docker 29.4
服务	systemd 管理（`kc-api`, `kc-mcp-http`, `kc-worker`, `caddy`）
域名	`kc.gjs.ink` `app.gjs.ink` `mcp.gjs.ink` `docs-kc.gjs.ink`

容器栈（5 个）

docker compose 配置在 /root/kc-deploy/
- kc-neo4j     :7474 :7687  (graph)
- kc-postgres  :5432         (relational + LightRAG KV/DocStatus)
- kc-milvus    :19530        (vector)
- kc-redis     :6379         (cache)
- kc-lightrag  :8020         (GraphRAG, 跑在上 4 个之上)

Go 服务（3 个，systemd）

kc-api.service       :3001  (REST + Web UI)
kc-mcp-http.service  :3000  (MCP HTTP transport)
kc-worker.service           (1h 演化周期)

二进制位于 /usr/local/bin/kc-{api,mcp-http,worker}，env 在 /root/kc-deploy/.env。

LLM / Embedding 配置

	模型	端点
LLM	`gpt-5.5`	`https://api.gjs.ink/v1` (OpenAI 兼容代理)
Embedding	`Qwen3-Embedding-8B` (4096 维)	`https://aiapi.ylzs.top/v1`

自托管路径

# 1. clone 主仓库
git clone https://github.com/hongnono-wdh/knowledge-chain.git
cd knowledge-chain/deploy

# 2. 写 .env (参考 .env.example)
cp ../.env.example ../.env  # 改里面的 API key

# 3. 起 5 容器
docker compose up -d

# 4. 编译 + systemd 跑 Go 服务
cd .. && make api-build  # 同时打包 web SPA
sudo cp bin/kc-* /usr/local/bin/
# 写 systemd unit (见仓库 docs/)
sudo systemctl enable --now kc-api kc-mcp-http kc-worker

# 5. 反代（Caddy 例）
# kc.example.com {
#   reverse_proxy localhost:3001 { flush_interval -1 }
# }

关键运维命令

# Go 服务重启
sudo systemctl restart kc-api kc-mcp-http kc-worker

# 容器栈管理
docker compose -f /root/kc-deploy/docker-compose.yml ps
docker compose -f /root/kc-deploy/docker-compose.yml logs -f kc-lightrag

# 数据迁移：dump Neo4j volume → tar → 拷到新机器解压
docker compose stop neo4j
docker run --rm -v kc-deploy_neo4j_data:/source -v /tmp:/backup busybox \
  tar czf /backup/neo4j.tar.gz -C /source .
docker compose start neo4j

# Neo4j → Milvus 重建索引（数据迁移后必跑）
/usr/local/bin/kc-resync

故障速查

现象	排查
`/healthz` 503 with `lightrag down`	`docker logs kc-lightrag` 看是否启动失败
`search` 返 `total_found: 0` 但 Neo4j 有数据	Milvus collection 空，跑 `kc-resync`
Worker `bind 9091 address in use`	跟 Milvus 冲突，加 `WORKER_METRICS_PORT=9092` 到 .env
LightRAG `Vector count mismatch`	`EMBEDDING_DIM` 不匹配，应为 4096 (Qwen3 原生维度)

监控

Prometheus 指标：kc-api/kc-mcp-http /metrics + kc-worker :9092/metrics
LightRAG WebUI：https://lightrag.example.com/webui（线上未公开，本地 :8020/webui）