Blinko 1.8.8 配置参数详解

目标：把 Blinko 的全部配置项讲透。Blinko 的配置分三层：进程环境变量（启动时注入，决定数据库连接、密钥、代理等运行骨架）、数据库持久化配置（config / aiProviders / aiModels 等表，控制台设置落库处）、控制台设置域（AI、S3、定时任务、Webhook、SSO、令牌、RSS、Hub 等功能开关与参数）。本文基于一个真实运行的 Blinko 1.8.8 + PostgreSQL 14.24 实例，所有命令与回显均为实测。部署过程见《Blinko Docker Compose 部署指南》，选型背景见《Blinko 介绍与选型指南》。

一、环境信息

本文取证所用的实验环境如下表，后文所有回显都出自这一套环境。

项目	值
操作系统	Ubuntu 26.04.1 LTS（x86_64）
应用版本	Blinko 1.8.8（2026-06-20 发布的最新稳定版）
数据库	PostgreSQL 14.24
运行时	Node.js 20.20.2
服务地址	服务内部监听 1111，对外发布 8141，本文所有示例访问 `http://localhost:8141`
管理员	admin（role=superadmin）
数据目录	`/app/.blinko`（files / pgdump / plugins / vector 四个子目录）
数据库口令	q1w2e3r4（实验环境，生产必须更换）

版本号不只看部署清单，实例自身也报告版本：

curl -s http://localhost:8141/api/v1/public/server-version

"1.8.8"

回显与官方 1.8.8 发布版本一致，说明配置取证对应的就是当前最新稳定版。

二、进程环境变量：64 处引用，10 项有效

Blinko 服务端代码通过 process.env 读取启动级配置。把生产包里的引用全部抽出来去重，可以得到一份变量清单：

grep -oE 'process\.env\.[A-Z][A-Z0-9_]*' server/index.js | sed 's/process\.env\.//' | sort -u > env_vars.txt
wc -l < env_vars.txt

process.env 变量总数: 64

64 个引用里大部分是构建工具与依赖库的噪音（CHOKIDAR_、PRISMA_、VITE_、DEBUG_、PATH/EDITOR/TMPDIR 等），对运维真正有意义的只有下表 10 项。

变量	作用	实测/建议值	说明
DATABASE_URL	PostgreSQL 连接串	`postgresql://postgres:q1w2e3r4@postgres:5432/postgres`	必填。Prisma 数据源，缺失则服务无法启动
NODE_ENV	运行模式	`production`	决定静态资源与迁移的加载模式
JWT_SECRET	令牌签名密钥	未注入，系统自动生成	可选；不配置时首启随机生成并持久化到 config 表（见第三章）
TRUST_PROXY	信任反向代理	`1`	部署在 Nginx/Traefik 之后必须开启
HTTP_PROXY / HTTPS_PROXY	出网代理	空	AI、联网搜索等出站请求走代理时配置
NO_PROXY	代理绕过清单	空	内网数据库、回环地址建议列入
IS_DEMO	演示模式	未设置	官方演示站用于限制破坏性操作
OPENAI_API_KEY	OpenAI 密钥兜底	未设置	建议改在控制台 AI 设置里配置
TAVILY_API_KEY	Tavily 联网搜索密钥	未设置	另有 TAVILY_HTTP_PROXY / TAVILY_HTTPS_PROXY 可单独指定代理
AZURE_OPENAI_ENDPOINT	Azure OpenAI 端点	未设置	使用 Azure 渠道时配置

启动日志头部可以直接验证运行模式与数据源解析结果：

Current Environment: production
Prisma schema loaded from prisma/schema.prisma
Datasource "db": PostgreSQL database "postgres" at "postgres:5432"

这两行回显说明：NODE_ENV=production 生效、DATABASE_URL 被正确解析为主机 postgres、端口 5432、库名 postgres。

💡 技术拓展：为什么 S3、AI、SSO 这些"看起来该进环境变量"的配置，官方都放到了控制台？因为它们落库后改完即生效、无需重启服务，且支持按用户维度覆盖（config 表的 userId 列）。环境变量只保留"启动前就必须知道"的最小集合——数据库地址、密钥、代理。实测进程环境中还会见到 NEXTAUTH_URL、NEXT_PUBLIC_BASE_URL、NEXTAUTH_SECRET 三项，它们服务于登录鉴权组件，取值应与对外访问地址一致（本环境为 http://localhost:8141）。

三、config 表：设置的持久化机制

控制台的键值型设置统一落在 config 表。表结构实测如下：

psql "postgresql://postgres:q1w2e3r4@127.0.0.1:5432/postgres" -c '\d config'

                                 Table "public.config"
 Column |       Type        | Collation | Nullable |              Default
--------+-------------------+-----------+----------+------------------------------------
 id     | integer           |           | not null | nextval('config_id_seq'::regclass)
 key    | character varying |           | not null | ''::character varying
 config | json              |           |          |
 userId | integer           |           |          |
Indexes:
    "config_pkey" PRIMARY KEY, btree (id)
Foreign-key constraints:
    "config_userId_fkey" FOREIGN KEY ("userId") REFERENCES accounts(id) ON UPDATE CASCADE ON DELETE SET NULL

结构解读：key 是设置名，config 是 JSON 值（形如 {"value":"..."}），userId 为空表示全局设置、非空表示该用户的个人设置；外键指向 accounts 表且 ON DELETE SET NULL，删号不炸表。

全新实例初始化后，表里只有两行：

psql "postgresql://postgres:q1w2e3r4@127.0.0.1:5432/postgres" -c 'select * from config order by id'

 id |    key     |                          config                          | userId
----+------------+----------------------------------------------------------+--------
  1 | JWT_SECRET | {"value":"h4Bmay0X61rGtQbvuDSQSPVBfm2qy7wCM9BC64nsyFQ="} |
  2 | theme      | {"value":"system"}                                       |      1
(2 rows)

两行信息量很大：第 1 行 JWT_SECRET 的 userId 为空——本环境并没有注入 JWT_SECRET 环境变量，系统首启自动生成了一个 52 字符随机密钥并持久化到了全局配置；第 2 行 theme 挂在 userId=1 下，是管理员的界面主题偏好。REST 侧也能读到它：

curl -s http://localhost:8141/api/v1/config/list -H "Authorization: Bearer $TOKEN"

{"theme":"system"}

3.1 AI 供应商与模型表

AI 相关配置不进 config 表，而是独立的 aiProviders / aiModels 两张表：

psql "postgresql://postgres:q1w2e3r4@127.0.0.1:5432/postgres" -c '\d "aiProviders"'

  Column   |            Type             | Collation | Nullable |                  Default
-----------+-----------------------------+-----------+----------+-------------------------------------------
 id        | integer                     |           | not null | nextval('"aiProviders_id_seq"'::regclass)
 title     | character varying(255)      |           | not null |
 provider  | character varying(50)       |           | not null |
 baseURL   | character varying(500)      |           |          |
 apiKey    | character varying(500)      |           |          |
 config    | json                        |           |          |
 sortOrder | integer                     |           | not null | 0
 createdAt | timestamp(6) with time zone |           | not null | CURRENT_TIMESTAMP
 updatedAt | timestamp(6) with time zone |           | not null |
Indexes:
    "aiProviders_pkey" PRIMARY KEY, btree (id)
Referenced by:
    TABLE ""aiModels"" CONSTRAINT "aiModels_providerId_fkey" FOREIGN KEY ("providerId") REFERENCES "aiProviders"(id) ON UPDATE CASCADE ON DELETE CASCADE

解读：一个供应商一行（provider 渠道名 + baseURL + apiKey + JSON 扩展配置），aiModels 表通过 providerId 外键挂在供应商下并级联删除——删供应商会连带删掉它的全部模型配置。

⚠️ 注意：apiKey 是 varchar(500) 明文列。数据库访问权限必须最小化，备份文件要按密级管理；任何把 user/list、库表内容暴露给外部的做法都可能连带泄露密钥（详见 API 篇的实测教训）。

3.2 数据目录

文件与向量数据不进数据库，落在 /app/.blinko：

ls -la /app/.blinko/files

total 3868
drwxr-xr-x    2 root     root          4096 Nov  1 11:14 .
drwxr-xr-x    6 root     root          4096 Nov  1 11:11 ..
-rw-r--r--    1 root     root       1360952 Nov  1 11:14 pic01.png
-rw-r--r--    1 root     root        971782 Nov  1 11:14 pic02.png
-rw-r--r--    1 root     root        141428 Nov  1 11:14 pic03.png
-rw-r--r--    1 root     root        589371 Nov  1 11:14 pic04.png
-rw-r--r--    1 root     root        875361 Nov  1 11:14 pic06.png
-rw-r--r--    1 root     root            12 Nov  1 11:14 story.txt

files/ 存附件与导出文件（上面 6 个文件是初始化种子笔记自带的示例附件）；pgdump/ 是数据库定时备份的落盘目录；vector/ 是 RAG 向量索引目录——实测该库的 PostgreSQL 扩展只有 plpgsql、没有 pgvector，向量存在文件系统而非库里；plugins/ 预留插件位。整个目录仅 3.8M，备份时与数据库转储一起打包即可。

四、控制台设置域逐项详解

除第二章的启动级变量外，其余功能配置都在管理界面完成并落库。下面按域逐个说明，AI 域的六个模型槽位可由接口枚举实测印证：

curl -s http://localhost:8141/api/v1/config/ai -H "Authorization: Bearer $TOKEN"

{"message":"Input validation failed","code":"BAD_REQUEST","data":{"code":"BAD_REQUEST","httpStatus":400,"path":"config.ai"},"issues":[{"code":"invalid_value","values":["mainModel","embeddingModel","voiceModel","rerankModel","imageModel","audioModel"],"path":["type"],"message":"Invalid option: expected one of \"mainModel\"|\"embeddingModel\"|\"voiceModel\"|\"rerankModel\"|\"imageModel\"|\"audioModel\""}]}

缺 type 参数的报错把合法值全吐了出来：主模型、嵌入、语音、重排、图像、音频共 6 类模型配置。补上参数后未配置的环境返回 null：

curl -s 'http://localhost:8141/api/v1/config/ai?type=mainModel' -H "Authorization: Bearer $TOKEN"

null

4.1 AI 设置（Setting AI）

AI 设置是所有智能功能的总开关，启用后按以下维度配置：

配置项	可选值/范围	建议
模型供应商	OpenAI、AzureOpenAI、Anthropic、DeepSeek、Gemini、Grok、Ollama、OpenRouter	本地隐私优先选 Ollama，聚合选 OpenRouter
主模型	按供应商选择	官方推荐 gpt-4o / gpt-4o-mini、claude-3-5-sonnet、deepseek-chat
API Key / Base URL	供应商密钥；自定义端点	走中转或私有部署时填 Base URL，留空用默认端点
Embedding 模型	text-embedding-3-small/large、voyage-3-lite、voyage-large-2 等	可独立配置嵌入的 Key 与端点
Embedding 维度	常见模型自动探测	自定义模型需手工指定
Embedding Top K	1-20	推荐 3-5，调大召回更多上下文
Embedding Score	0.0-1.0	推荐 0.4-0.7，调高只留强相关
Rerank	目前需大模型（如 GPT-4）	官方说明 AI SDK 尚不支持专用重排模型
HTTP 代理	开关+地址	出网受限环境开启

换嵌入模型后必须重建索引：Rebuild 是增量更新，Force Rebuild 全量重算——不同模型的向量维度与语义空间不兼容，不重建则检索结果错乱。配置完点 "Test Connection" 验证密钥、端点与网络连通性。

AI 增强搜索（Ctrl+K 唤起）直接复用本节参数：语义检索支持文本、PDF、附件内容，图片内容需多模态模型；AI 对话时自动做知识库检索。

4.2 S3 存储

默认附件写本地 files/ 目录；接对象存储后改为写 S3。五个字段缺一不可：

字段	含义	示例
Access Key ID	访问标识	MinIO 控制台创建
Access Key Secret	配对密钥	妥善保存，仅创建时可见
Endpoint	服务地址	AWS 为 `https://s3.<region>.amazonaws.com`；MinIO 填自建地址
Region	区域	AWS 必填，MinIO 可随意
Bucket	存储桶名	需预先创建并配好权限

流程：建桶 → 生成密钥 → 填端点 → 用界面的上传/下载测试验证。AWS S3、MinIO 及任何 S3 兼容服务均可。

4.3 定时任务（Schedule Task）

Blinko 内置 pg-boss 任务队列，启动日志实测回显：

Initializing pg-boss scheduled jobs...
ℹ Fonts directory not found: /app/app/public/fonts
🔤 Seeding fonts...
   🌐 CDN fonts: 31
   📁 Local fonts: 0
[pg-boss] Started successfully
[auto-archive-blinko] Worker registered
[auto-archive-blinko] Initialized with default schedule: 0 0 * * *
[backup-database] Worker registered
[backup-database] Initialized with default schedule: 0 0 * * *
[rebuildEmbedding] Worker registered
[rebuildEmbedding] Initialized with default schedule: 0 0 * * *
[follow-recommand-index] No followings found, skipping initialization
✨ Seed done! ✨
[AI Scheduled Task] Worker registered
All scheduled jobs initialized successfully

三个内置 worker 的默认排程都是 0 0 * * *（每天 0 点）：auto-archive-blinko 自动归档碎片、backup-database 数据库备份（落 pgdump/）、rebuildEmbedding 重建向量索引；follow-recommand-index 因无关注关系被跳过；AI Scheduled Task 承载用户自建的 AI 定时任务。

控制台"定时任务"页提供两个开关：Schedule Back Up（按间隔天数自动备份，如每 5 天）与 Schedule Archive Blinko（同间隔自动归档）。任务表格五列：Name（Backup Database / Auto Archive Blinko）、Schedule（频率）、Last Run（上次执行）、Backup File（产物路径，如 .blinko/files/blinko_export.bko，可直接下载）、Status（Running/Paused）。

💡 说明：.bko 导出文件与数据库备份是两条独立产物——前者是笔记内容归档，后者是整库转储，灾难恢复时优先用数据库备份。

4.4 Webhook

Settings > Webhook 中填一个回调 URL 即可订阅三类事件：Note Create / Note Update / Note Delete。载荷格式实测文档给出的样例：

{
  "webhookType": "user.create",
  "activityType": "blinko.note.update",
  "data": {
    "id": 0,
    "type": 0,
    "content": "",
    "isArchived": false,
    "isShare": false,
    "attachments": []
  }
}

activityType 标识事件类型，data 是笔记完整对象（含附件数组）。官方安全建议：仅用 HTTPS 端点、实现签名校验、接收端做 IP 白名单、配置超时，并为关键事件保留兜底通知通道；高流量期回调可能延迟。

4.5 SSO 单点登录

基于 OAuth2.0，内置 13 个平台模板：GitHub、Google、Facebook、Apple、Spotify、Discord、Twitter、Slack、Twitch、LINE、Instagram、Coinbase、Yandex——选模板只需填 Client ID / Client Secret。模板外的身份提供方走 Custom Provider，手工填 WellKnown URL、Authorization URL、Token URL、User Info URL 四个端点及权限范围。

回调地址固定格式，必须预先加到身份提供方的允许清单里：

http(s)://{你的域名}/api/auth/callback/{providerId}

⚠️ 注意：Client Secret 只在服务端使用，绝不出现在前端代码；端点一律 HTTPS，密钥定期轮换，授权范围最小化。

4.6 Access Token（API 令牌）

Settings > Access Token 生成 JWT 令牌（eyJ... 开头），供 Blinko Snap 等客户端和 REST API 认证。官方给出的验证命令（把令牌粘进去）：

curl -X POST 'http://localhost:8141/api/v1/note/upsert' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -d '{"content": "🎉 Hello, Blinko! --send from api", "type": 0}'

要点：复制令牌不要带入空格；粘贴后客户端会自动测连接；令牌过期或疑似泄露就重新生成。实测中 user/list 接口的 apiToken 字段返回的就是这类长期令牌，详见 API 篇。

4.7 RSS 订阅

公开笔记可被 RSS 阅读器订阅，两种格式、按用户取：

/api/rss/{userId}/atom?row=20
/api/rss/{userId}/rss?row=20

row 控制返回条数（默认 20）。入选条件只有两条：设为公开且无访问密码——私有笔记、带密码的分享一律排除，改隐私设置立即影响订阅内容。

实测注意：直接访问 /api/rss 返回 404：

curl -s -o /dev/null -w '%{http_code}' http://localhost:8141/api/rss

这不是功能损坏——RSS 路由必须带 userId 与格式后缀，裸路径本就无定义。

4.8 Hub 与外部 MCP 服务

Blinko Hub 是实例间的去中心化发现网络：在 blinko-hub 注册站点（title、url、tags 三项配置），公开碎片即可进入全局目录，支持 P2P 互联、按标签发现实例、自动交换反链。个人实例可完全忽略此域。

"外部 MCP 服务"页用于把 Blinko 作为客户端接入第三方 MCP 服务，实测新实例为空：

curl -s http://localhost:8141/api/v1/mcp-servers/list -H "Authorization: Bearer $TOKEN"

[]

注意区分：这个页面管理的是"我连别人"；Blinko 自身对外提供的 MCP 服务端挂在 /mcp 路径，属于 API 范畴，见 API 篇。

五、生产配置模板

综合以上三层，生产部署建议按下面这份清单固化（键值对形式，适用于任何注入环境变量的方式）：

# ---- 必填 ----
NODE_ENV=production
DATABASE_URL=postgresql://blinko:<强口令>@<db主机>:5432/blinko

# ---- 强烈建议显式固定 ----
JWT_SECRET=<openssl rand -base64 48 生成，纳入备份>
NEXTAUTH_SECRET=<同类随机串>
NEXTAUTH_URL=https://notes.example.com
NEXT_PUBLIC_BASE_URL=https://notes.example.com

# ---- 反向代理之后必开 ----
TRUST_PROXY=1

# ---- 时区与出网 ----
TZ=Asia/Shanghai
# HTTP_PROXY=http://127.0.0.1:7890
# HTTPS_PROXY=http://127.0.0.1:7890
# NO_PROXY=localhost,127.0.0.1,<内网网段>

# ---- 可选兜底（优先用控制台配置）----
# OPENAI_API_KEY=
# TAVILY_API_KEY=
# AZURE_OPENAI_ENDPOINT=
# IS_DEMO=

要点解读：JWT_SECRET 与 NEXTAUTH_SECRET 若交给系统自动生成，重建环境后所有登录态与 API 令牌全部失效，因此生产要显式固定并纳入备份；NEXTAUTH_URL 必须等于对外访问地址，否则登录回调跳错主机；代理三变量只在出网受限时开启，且务必把数据库地址写进 NO_PROXY。

六、常见问题 FAQ

Q1：JWT_SECRET 不配会怎样？ 不会怎样——实测本环境未注入该变量，首启自动生成了随机密钥并写入 config 表全局行（value 为 h4Bmay0X...）。但生产仍建议显式固定，避免重建环境后令牌集体失效。

Q2：为什么反代之后必须 TRUST_PROXY=1？ 不开启时应用看到的是代理的地址而非真实客户端 IP，协议判断也停留在 HTTP，导致跳转、限流、审计日志全部失真。

Q3：config/list 为什么只返回 theme？ 该接口返回的是当前用户的键值设置；AI/S3 等走各自的专用表与接口（aiProviders、config/ai 等），不混在 config 表里。

Q4：换了嵌入模型检索结果不对？ 正常现象，必须重建索引（增量 Rebuild 或全量 Force Rebuild）。后台 rebuildEmbedding 任务默认每天 0 点也会跑，但改模型后建议手动立即触发。

Q5：备份到底备什么？ 备两样：PostgreSQL 转储（backup-database 任务落 pgdump/）+ /app/.blinko 整个目录（附件、导出、向量索引）。数据库里没有向量，光备库恢复不了语义检索。

Q6：API Key 存在哪，安全吗？ 存在 aiProviders.apiKey 明文列。数据库账号最小权限、备份加密、不要把 user/list 这类返回敏感字段的接口暴露到公网。

Q7：RSS 返回 404 是不是没开？ 不是，路径要写全：/api/rss/<userId>/rss 或 /api/rss/<userId>/atom，且笔记需设为公开无密码。

七、参考链接

《Blinko 介绍与选型指南》 —— 版本线与竞品对比
《Blinko Docker Compose 部署指南》 —— 本文实验环境的搭建过程
《Blinko 1.8.8 API 使用详解》 —— 配置项的 API 侧验证
Blinko 官方文档：https://docs.blinko.space/ （Setting AI / S3 Storage / Schedule Task / Webhook / SSO / Access Token / RSS Feed / Blinko Hub）
Blinko 源码仓库：https://github.com/blinko-space/blinko
Blinko Hub：https://github.com/blinko-space/blinko-hub