在 Starcat 中配置自托管 API

设置 → 服务：自定义 URL、API Key、测试连接与重置

​

入口

设置 → 服务

页顶说明：「配置 Starcat 后端服务地址。」每个服务一张卡片，含：

控件	作用
自托管 链接	打开该服务的 GitHub 源码仓库
URL	自定义 baseURL；留空则用官方默认
API Key	覆盖该服务的 Bearer Token；留空则用 App 内置生产 Key
测试连接	请求 GET /api/v1/ping（带鉴权）
重置	清掉该服务的自定义 URL 与 Key，回到内置默认

​

填写规则

1. URL 只填服务根，不要带业务 path，也不要末尾多余 /。
   • 正确：http://127.0.0.1:5002 或 https://trending.example.com
   • 错误：http://127.0.0.1:5002/api/v1、…/api（历史 Sharing 带 /api 的写法会在保存时被规范化剥掉）
2. API Key 必须是你自托管实例 API_KEYS 白名单中的某一个。
   客户端优先级：本页自定义 Key → App 内置生产 Key → 都没有则请求不带 Authorization（通常 401）。
3. 点 测试连接：成功表示地址可达、Key 正确、且 data.service 与卡片服务一致（防填错端口）。
4. 可只覆盖部分服务（例如只自托管 Discovery，趋势仍用官方）。

​

与本页无关的「自托管」

能力	入口	说明
Meilisearch / Qdrant（RAG 可选检索）	设置 → AI	不是 Go 支持 API，不在「服务」Tab
AI Provider Base URL	设置 → AI	BYOK 模型端点
Direct License	无用户覆盖入口	支付 / 授权，不在本专题

​

本地联调示例

假设本机已按 自部署 启动全部 API：

服务	URL 示例
Sharing	http://127.0.0.1:5001
Trending	http://127.0.0.1:5002
Weekly	http://127.0.0.1:5003
Wiki	http://127.0.0.1:5004
Recommend	http://127.0.0.1:5005
Discovery	http://127.0.0.1:5006

每张卡片填入同一套或各服务独立的 Key，逐个「测试连接」。

​

生效方式

保存后，App 会热更新对应客户端的 baseURL / Key（无需重启整个 App；若个别面板仍显示旧数据，切换分区或手动刷新即可）。

状态栏上的服务可用性巡检走 /healthz（不校验 Key），与设置页「测试连接」语义不同：

入口	路径	鉴权	含义
设置 → 测试连接	/api/v1/ping	Bearer	地址 + Key + 服务身份
状态栏可用性	/healthz	无	进程是否在线

​

排障

现象	排查
无法连接	防火墙 / 是否监听 0.0.0.0；本机请用 127.0.0.1
Unauthorized	Key 未写入服务端 API_KEYS，或客户端填错
服务不匹配	URL 指到了另一个端口上的服务
业务 404	baseURL 多写了 /api 或 path；应只保留 host:port
趋势/发现为空	自托管实例尚未完成抓取；查该服务日志与 GitHub PAT 配额

​

相关

• 自托管概览
• 自部署
• 设置 · 集成（插件 / External Search，与后端 API 不同）