Blinko Docker Compose 部署指南

目标：在 Ubuntu 26.04.1 LTS 服务器上以 Docker Compose 部署 Blinko 1.8.8（配套 PostgreSQL 14），完成首次启动的数据库初始化、健康检查与管理员初始化，并实录「website 卡在 Created 未启动」的排障过程。本文所有命令与输出均来自同一环境的实测回显。选型背景见《Blinko 介绍与选型指南》。

一、环境信息

操作系统：Ubuntu 26.04.1 LTS（x86_64）
Docker：29.9.2（build a82e528）
Docker Compose：v5.6.1
应用：blinkospace/blinko:1.8.8（本地已拉取，1.74GB）
数据库：postgres:14（本地已拉取，629MB）
部署目录：/opt/blinko-188-stack
端口：应用内部监听 1111，对外发布 8141；本文所有示例访问 http://localhost:8141
数据持久化：宿主机 /opt/blinko-188-stack/db-data 挂数据库数据目录，/opt/blinko-188-stack/blinko-data 挂应用 /app/.blinko
版本线：Blinko 1.8.8 为当前最新稳定版（2026-06-20 发布），官方配套 PostgreSQL 14.24、Node.js 20.20.2

docker --version && docker compose version

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

💡 说明：官方 compose 模板使用 blinkospace/blinko:latest 浮动标签，本文锁定 1.8.8，升级动作显式化，避免自动跳版。

二、准备部署目录

mkdir -p /opt/blinko-188-stack/db-data /opt/blinko-188-stack/blinko-data

mkdir -p 成功时静默无输出，目录已存在也不报错。两个数据目录的作用：

宿主机路径	挂载目标	存放内容
`/opt/blinko-188-stack/db-data`	`/var/lib/postgresql/data`	PostgreSQL 全部表数据（笔记、标签、配置、用户）
`/opt/blinko-188-stack/blinko-data`	`/app/.blinko`	上传文件、数据库备份、插件、向量索引（详见「六」的目录实测）

⚠️ 注意：官方文档明确警告——postgres 的数据卷必须挂载，否则数据会丢。compose 模板里官方把 volumes 注释掉了，照抄模板时务必取消注释。

三、编写 docker-compose.yml

在 /opt/blinko-188-stack 下创建 docker-compose.yml，全文如下（本次实测使用的完整文件）：

name: blinko-188-stack

networks:
  blinko-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.61.0/24

services:
  postgres:
    image: postgres:14
    container_name: blinko-188-postgres
    restart: always
    environment:
      POSTGRES_DB: postgres
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: q1w2e3r4
      TZ: Asia/Shanghai
    volumes:
      - /opt/blinko-188-stack/db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres", "-d", "postgres"]
      interval: 5s
      timeout: 10s
      retries: 5
    networks:
      - blinko-net

  blinko-website:
    image: blinkospace/blinko:1.8.8
    container_name: blinko-188-website
    restart: always
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      NODE_ENV: production
      NEXTAUTH_URL: http://localhost:8141
      NEXT_PUBLIC_BASE_URL: http://localhost:8141
      NEXTAUTH_SECRET: S4c7TestSecretForBlinkoDocDemo2026==
      DATABASE_URL: postgresql://postgres:q1w2e3r4@postgres:5432/postgres
      TZ: Asia/Shanghai
    ports:
      - "8141:1111"
    volumes:
      - /opt/blinko-188-stack/blinko-data:/app/.blinko
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://blinko-website:1111/"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - blinko-net

关键参数逐项解读：

参数	本文取值	说明
`networks.blinko-net.ipam.subnet`	`10.89.61.0/24`	固定网段，避免与既有网络冲突，也便于容器内互访排查
`postgres.image`	`postgres:14`	Blinko 官方配套 PostgreSQL 14 线，勿擅自升到 15+
`postgres.healthcheck`	`pg_isready`	是 `depends_on: service_healthy` 生效的前提
`blinko-website.depends_on`	`condition: service_healthy`	等数据库健康后再启动应用，首启迁移才能连上库（也是「七」排障的线索）
`NEXTAUTH_URL` / `NEXT_PUBLIC_BASE_URL`	`http://localhost:8141`	对外访问地址；若走 SSO，官方要求必须填真实域名
`NEXTAUTH_SECRET`	演示值	会话签名密钥，生产必须换成随机值（见下方警告）
`DATABASE_URL`	指向服务名 `postgres:5432`	容器网络内用服务名解析，不要写 127.0.0.1
`ports`	`8141:1111`	1111 是应用默认监听端口；8141 为对外发布端口，避开同机 1111 占用
`logging`	10m×3	官方模板自带，防日志撑爆磁盘

⚠️ 注意：NEXTAUTH_SECRET 与 POSTGRES_PASSWORD 在本文中是演示值。官方安装文档对此有专门的安全警告：所有安装方式都必须更换 NEXTAUTH_SECRET，使用默认值存在重大安全风险。生产环境生成方式：
openssl rand -base64 32

四、启动与重启验证

首次启动前，先确认 compose 文件所在目录正确，然后执行：

cd /opt/blinko-188-stack && docker compose up -d

本次实测在首次启动时遭遇了「website 卡在 Created 未启动」的问题（现象、根因与修复见「七」）。修复后按「先停干净、再整体拉起」做了完整的重启验证，两步回显如下。

第一步，停止并清理：

docker compose down

 Container blinko-188-website Stopping 
 Container blinko-188-website Stopped 
 Container blinko-188-website Removing 
 Container blinko-188-website Removed 
 Container blinko-188-postgres Stopping 
 Container blinko-188-postgres Stopped 
 Container blinko-188-postgres Removing 
 Container blinko-188-postgres Removed 
 Network blinko-188-stack_blinko-net Removing 
 Network blinko-188-stack_blinko-net Removed

第二步，重新拉起（注意应用先「Waiting → Healthy」再「Starting → Started」的顺序，说明 depends_on 健康门控生效）：

docker compose up -d

 Network blinko-188-stack_blinko-net Creating 
 Network blinko-188-stack_blinko-net Creating 
 Network blinko-188-stack_blinko-net Created 
 Network blinko-188-stack_blinko-net Created 
 Container blinko-188-postgres Creating 
 Container blinko-188-postgres Created 
 Container blinko-188-website Creating 
 Container blinko-188-website Created 
 Container blinko-188-postgres Starting 
 Container blinko-188-postgres Started 
 Container blinko-188-postgres Waiting 
 Container blinko-188-postgres Healthy 
 Container blinko-188-website Starting 
 Container blinko-188-website Started

五、首次启动日志：30 个迁移与定时任务注册

应用启动时会自动执行 Prisma 数据库迁移并注册内置定时任务，无需手工初始化建表。完整首启日志（docker compose logs blinko-website 节选，迁移段与初始化段原样照录）：

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

30 migrations found in prisma/migrations

Applying migration `20241026033301_0_0_1`
Applying migration `20241027072348_0_0_3`
Applying migration `20241112084821_0_2_9`
Applying migration `20241121082228_0_6_0`
Applying migration `20241202103221_0_12_11`
Applying migration `20241205035247_18_0_1`
Applying migration `20241212033352_0_23_3`
Applying migration `20241218023101_0_27_0`
Applying migration `20241219062514_0_27_7`
Applying migration `20241226141834_0_30_7`
Applying migration `20241231014246_0_32_0`
Applying migration `20250101032000_0_32_4`
Applying migration `20250108081202_0_34_0`
Applying migration `20250110011520_0_34_13`
Applying migration `20250110022717_0_34_15`
Applying migration `20250110105226_0_36_0`
Applying migration `20250115050059_0_37_0`
Applying migration `20250116052731_0_37_4`
Applying migration `20250219083523_0_39_0`
Applying migration `20250222125610_0_41_0`
Applying migration `20250306102203_0_42_4`
Applying migration `20250331072252_0_48_0`
Applying migration `20250418115430_1_0_0`
Applying migration `20250529145705_1_0_4`
Applying migration `20250921064614_1_5_0`
Applying migration `20250922040757_1_5_1`
Applying migration `20250930000000_add_sort_order_to_notes`
Applying migration `20251221120939_add_mcp_servers`
Applying migration `20251221193000_pg_boss_migration`
Applying migration `20251231140909_add_fonts_table`

The following migration(s) have been applied:

All migrations have been successfully applied.

迁移完成后，进程继续初始化字体种子与定时任务引擎：

ℹ Fonts directory not found: /app/app/public/fonts
🔤 Seeding fonts...
   🌐 CDN fonts: 31
   📁 Local fonts: 0
✨ Seed done! ✨
Initializing pg-boss scheduled jobs...
[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
[AI Scheduled Task] Worker registered
All scheduled jobs initialized successfully
7:11:19 PM [vite-express] Running in production mode
7:11:19 PM [vite-express] Inline config detected, ignoring Vite config file
7:11:19 PM [vite-express] Serving static files from /app/server/public
🎉server start on port http://0.0.0.0:1111 - env: production

解读三点：

迁移即建表：30 个迁移从 20241026033301_0_0_1 一路排到 20251231140909_add_fonts_table，其中 add_mcp_servers 与 pg_boss_migration 是 1.x 时代新增 MCP 服务管理和任务引擎的痕迹——表结构、定时任务全部开箱自带。
pg-boss 三个默认 worker：auto-archive-blinko（Blinko 碎片自动归档）、backup-database（数据库定时备份）、rebuildEmbedding（向量索引重建），默认调度都是 0 0 * * *（每日零点），频率可在设置界面调整（见《Blinko 1.8.8 配置参数详解》）。
监听 0.0.0.0:1111：应用内部固定监听 1111，对外端口由 compose 的 ports 决定，与官方模板注释一致。

六、部署验证

1. 服务状态。 等待健康检查通过后查看：

docker compose ps

NAME                  IMAGE                      COMMAND                  SERVICE          CREATED          STATUS                    PORTS
blinko-188-postgres   postgres:14                "docker-entrypoint.s…"   postgres         12 seconds ago   Up 12 seconds (healthy)   5432/tcp
blinko-188-website    blinkospace/blinko:1.8.8   "docker-entrypoint.s…"   blinko-website   12 seconds ago   Up 6 seconds (healthy)    0.0.0.0:8141->1111/tcp, [::]:8141->1111/tcp

两个服务均为 Up (healthy)，数据库 5432 端口只在内部网络暴露、未发布到宿主机，符合预期。

2. HTTP 连通性。

curl -sI http://localhost:8141/ | head -3

HTTP/1.1 200 OK
X-Powered-By: Express
Vary: Origin

curl -s http://localhost:8141/ | grep -o '<title>.*</title>'

<title>Blinko</title>

3. 版本与健康接口。

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

"1.8.8"

curl -s http://localhost:8141/health

{"status":"ok"}

server-version 返回 "1.8.8"，与 compose 中锁定的版本一致，确认没有跑错版本。

4. 数据目录落盘。 应用运行数据全部写入挂载的 /app/.blinko：

ls -l /app/.blinko

total 24
drwxr-xr-x    6 root     root          4096 Nov  1 11:11 .
drwxr-xr-x    1 root     root          4096 Nov  1 11:11 ..
drwxr-xr-x    2 root     root          4096 Nov  1 11:14 files
drwxr-xr-x    2 root     root          4096 Nov  1 11:11 pgdump
drwxr-xr-x    2 root     root          4096 Nov  1 11:11 plugins
drwxr-xr-x    2 root     root          4096 Nov  1 11:11 vector

du -sh /app/.blinko

3.8M	/app/.blinko

四个子目录各司其职：files 存上传附件（实测内含 pic01.png 等示例图片与 story.txt），pgdump 留数据库备份，plugins 装插件，vector 放向量索引。初始体量 3.8M，备份时把挂载的两个宿主机目录一起打包即可。

5. 管理员初始化。 浏览器打开 http://localhost:8141，首次访问进入注册页，创建超级管理员账号（本文实测使用 admin / q1w2e3r4）。注册完成后用公开接口验证账号已就位：

curl -s http://localhost:8141/api/v1/public/site-info

{"id":1,"name":"admin","image":"","description":"","role":"superadmin"}

role 为 superadmin，初始化完成。

七、排障实录：website 卡在 Created 未启动

现象：首次执行 docker compose up -d 后，docker compose ps 显示 postgres 已启动，而 blinko-188-website 停留在 Created 状态、始终不进入 Started，8141 端口无监听。对照「四」中修复后的正常回显，正常序列应当是 Created → postgres Starting/Started → postgres Waiting → postgres Healthy → website Starting/Started，卡住时流程停在 Container blinko-188-website Created 之后。

根因：compose 里 blinko-website 配置了 depends_on: postgres: condition: service_healthy。首次启动时 postgres 初始化数据目录（建库、跑 initdb）耗时较长，健康检查尚未转为 healthy，此时 up 流程被中断（终端 Ctrl+C），website 已创建但永远等不到健康门放行，于是停在 Created。这不是 Blinko 的缺陷，而是 service_healthy 门控与中断操作叠加的正常表现。

修复：确认 postgres 已 healthy 后，重新执行一次拉起命令即可，无需 down：

docker compose up -d

 Container blinko-188-postgres Waiting 
 Container blinko-188-postgres Healthy 
 Container blinko-188-website Starting 
 Container blinko-188-website Started

随后 docker compose ps 中 website 进入 Up (healthy)，即「六」验证时的状态。

💡 说明：若反复卡在 Waiting，说明数据库健康检查始终不过，应 docker compose logs postgres 检查 postgres 本身；排查顺序永远是「先库后应用」。

八、更新与日常运维

版本更新（以 1.8.8 → 后续版本为例）：

sed -i 's/blinkospace\/blinko:1.8.8/blinkospace\/blinko:<新版本>/' docker-compose.yml
docker compose pull blinko-website
docker compose up -d

只重建应用服务，postgres 数据不受影响；迁移会在应用启动时自动执行（见「五」）。官方也提供 update.sh 脚本，其本质是对单实例方式的更新包装，compose 部署推荐直接改标签。

⚠️ 注意：官方更新文档专门警告——使用 watchtower 自动更新时，绝不能把 postgres 纳入监控对象，否则数据库被重建、数据会丢。若用 watchtower，只指定 blinko-website 一个目标。

停止与彻底清理：

docker compose down          # 停止并移除，保留挂载数据
docker compose down --volumes  # 连命名卷一起清理（本文用绑定挂载，数据在宿主机目录，需手工删除才彻底清空）

备份：内置 backup-database 定时任务默认每日零点导出数据库备份到 .blinko/files/（官方文档示例文件名 blinko_export.bko）；稳妥做法是同时定期打包宿主机 db-data 与 blinko-data 两个目录。

九、常见问题

website 一直 Created 不启动：见「七」，先确认 postgres healthy，再 docker compose up -d 补一次拉起。
重启后登录态失效：NEXTAUTH_SECRET 每次随机生成导致旧会话签名作废；该值必须固定并妥善保存（这也是官方要求必须替换默认值的另一层含义）。
数据库重启后数据全空：postgres 未挂载数据卷，容器删除即数据归零——官方警告过的头号事故，按「二」的表检查挂载。
8141 被占用：改 ports 左侧发布端口即可，应用内部 1111 不要动；若走反代/HTTPS，同步修改 NEXTAUTH_URL 与 NEXT_PUBLIC_BASE_URL 为对外真实地址。
SSO 回调失败：官方要求使用 SSO 时 NEXTAUTH_URL 必须是真实域名，localhost 下 OAuth 回调无法工作。

十、参考链接

官方安装文档（含官方 compose 模板与 NEXTAUTH_SECRET 安全警告）：https://docs.blinko.space/install
官方更新文档（含 watchtower 勿纳入 postgres 警告）：https://docs.blinko.space/update
官方定时任务文档：https://docs.blinko.space/settings/task
Blinko 仓库与 Releases：https://github.com/blinko-space/blinko
站内配套阅读：《Blinko 介绍与选型指南》、《Blinko 1.8.8 配置参数详解》、《Blinko 1.8.8 API 使用详解》