Outline 部署教程：4 万 Star 自托管知识库，免费替代 Notion（Windows 源码部署完整指南）

GitHub 41k Star：Outline

从零部署完整教程 · 新手照着做就能跑起来 · 效率工具指南 · 原创教程

摘要：Outline 自托管知识库部署教程：本文在 Windows 上从零搭建 Outline（Notion/Confluence 开源替代），涵盖 Node.js、PostgreSQL、Redis、SMTP 四件套安装配置、源码构建、数据库迁移与邮件魔法链接登录，附 8 个真实踩坑的完整解决方案与一键命令速查。

Notion 团队版按人头收费、数据存在别人服务器上、国内访问时快时慢------如果你也遇到这些问题，可以试试用完全开源免费的 Outline 自建一个私有知识库。它支持实时协作、文档集权限、全文搜索、版本历史，41k Star、中文界面完整。本文基于一台普通 Windows 电脑，从装环境开始完整跑通全部流程，并整理了 8 个踩坑的解决方案（含 2 个 Windows 平台级 bug），跟着做就能得到一个完全属于你自己的知识库。

本文要点

技术栈：TypeScript / Node.js + PostgreSQL + Redis，本文验证 Windows 源码部署（无需 Docker）
四件套从零安装：Node.js、PostgreSQL 免安装 zip、Redis、SMTP 邮箱服务，每步附验证方法
8 个真实踩坑：含 2 个 Windows 平台级 bug（构建脚本 Unix 命令兼容、插件加载路径匹配失效），已完成修复方案
登录机制详解：邮箱魔法链接（Magic Link）全流程，含本地测试方案
中文搜索的正确理解：Postgres 分词机制导致的「前缀匹配」现象与应对技巧

一、项目简介

Outline（outline/outline）是一款开源的团队知识库系统，定位是 Notion / Confluence 的自托管替代品。它提供所见即所得的 Markdown 编辑、实时多人协作、文档集分组与权限管理、全文搜索、版本历史、评论和公开分享等功能，界面简洁、中文支持完整。

与 Notion 等 SaaS 服务不同，Outline 部署在你自己的设备上：所有数据（文档、附件、账号）都在本地，不依赖第三方云服务，没有订阅费，数据完全属于自己。

二、GitHub 项目数据

项目主页：https://github.com/outline/outline

项目	数据
Star	41k
主要语言	TypeScript
技术栈	Node.js + React + PostgreSQL + Redis
核心功能	实时协作、文档集权限、全文搜索、版本历史、公开分享
活跃度	持续活跃（近期每周有提交）

三、环境准备

Outline 需要四个组件配合：Node.js （运行服务）、PostgreSQL （存数据）、Redis （缓存与任务队列）、SMTP 邮箱服务（发送登录链接）。

组件	要求
Node.js	20.12+ 或 22 LTS 或 24（推荐装 22 LTS 或 24）
PostgreSQL	15 及以上
Redis	5 及以上
SMTP	任意邮箱服务（QQ 邮箱、163、Gmail 均可）

3.1 安装 Node.js

官网 https://nodejs.org/zh-cn 下载 LTS 版本（.msi），双击安装，一路下一步（Add to PATH 保持勾选）。

验证（新开 PowerShell）：

bash 复制代码

node -v
npm -v

两个命令都输出版本号即成功（本项目同时用到 yarn 4，Node 自带 corepack 可自动处理，无需单独安装）。

3.2 安装 PostgreSQL（免安装 zip 版）

下载 EDB 官方的二进制 zip（约 320MB）：

bash 复制代码

https://get.enterprisedb.com/postgresql/postgresql-17.6-1-windows-x64-binaries.zip

⚠️ 解压时如提示「路径过长」失败，跳过内部的 pgAdmin 目录即可------我们只需要 pgsql/bin、lib、share 这几部分。

解压后初始化并启动数据库（在解压出的 pgsql 同级目录执行）：

bash 复制代码

# 初始化数据目录（本地免密模式，供个人/内网使用）
pgsql\bin\initdb.exe -D pgdata -U postgres -A trust -E UTF8 --no-locale

# 启动数据库
pgsql\bin\pg_ctl.exe -D pgdata -l pglog.txt start

# 创建 Outline 专用用户与数据库
pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -c "CREATE USER outline WITH PASSWORD 'outline_pass' SUPERUSER;"
pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -c "CREATE DATABASE outline OWNER outline;"

验证：

bash 复制代码

pgsql\bin\psql.exe -U outline -h 127.0.0.1 -d outline -c "SELECT 1;"
# 输出 1 即成功

💡 长期使用建议把 PostgreSQL 注册为 Windows 服务（pg_ctl register 命令），开机自动启动，无需每次手动开。

3.3 安装 Redis

Windows 使用社区维护的免安装版本（约 12MB）：

bash 复制代码

https://ghproxy.net/https://github.com/tporadowski/redis/releases/download/v5.0.14.1/Redis-x64-5.0.14.1.zip

解压后运行 redis-server.exe --port 6379 启动。验证：

bash 复制代码

redis-cli.exe ping
# 返回 PONG 即成功

3.4 准备 SMTP 邮箱服务

Outline 的登录依赖邮件：输入邮箱后，系统把「魔法登录链接」发到你的邮箱，点链接即登录。所以需要一个能发信的邮箱。

以 QQ 邮箱为例（其他邮箱同理）：登录网页版邮箱 → 设置 → 账户 → 开启 SMTP 服务并生成「授权码」（配置里当密码用）。记住这组信息：SMTP 服务器地址（smtp.qq.com）、端口（465）、账号、授权码。

💡 只想本机测试、不想配真实邮箱？可以用 Mailpit、smtp4dev 这类本地邮件接收工具暂时代替，邮件会显示在它们的网页界面里（登录流程完全一样）。

四、详细部署步骤

4.1 获取源码并安装依赖

bash 复制代码

git clone https://github.com/outline/outline.git
cd outline

# 国内网络配置镜像源（官方源慢的话）
yarn config set npmRegistryServer https://registry.npmmirror.com

yarn install

依赖约 1900 个包、近 1GB，国内镜像源下载大约 15 分钟，耐心等待。

4.2 配置 .env

在项目根目录新建 .env 文件：

bash 复制代码

NODE_ENV=production
URL=http://127.0.0.1:3000
PORT=3000
SECRET_KEY=换成64位随机十六进制串
UTILS_SECRET=换成另一个64位随机十六进制串
DEFAULT_LANGUAGE=zh_CN
DATABASE_URL=postgres://outline:outline_pass@127.0.0.1:5432/outline
REDIS_URL=redis://127.0.0.1:6379
FILE_STORAGE=local
FILE_STORAGE_LOCAL_ROOT_DIR=附件存放目录的绝对路径
FORCE_HTTPS=false
PGSSLMODE=disable
SMTP_HOST=smtp.qq.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USERNAME=你的邮箱@qq.com
SMTP_PASSWORD=你的授权码
SMTP_FROM_EMAIL=你的邮箱@qq.com

💡 SECRET_KEY 与 UTILS_SECRET 用随机串生成，例如 Python：python -c "import secrets; print(secrets.token_hex(32))"。生成后不要随意更换（SECRET_KEY 变了会导致已登录用户失效）。

4.3 Windows 下的两处修复（必做）

Windows 上运行 Outline 需要修补两个平台兼容问题（原因详见第六节坑 5、坑 6），先做，避免后面反复：

修复一：插件加载路径方式 ------编辑 server/utils/PluginManager.ts，把 glob.sync 那一行改为：

javascript 复制代码

glob.sync(path.join(rootDir, "plugins/*/server/index.[jt]s"), { windowsPathsNoEscape: true })

修复二：构建脚本的静态文件复制------构建完成后需手动补一步（见 4.5）。

4.4 数据库迁移

bash 复制代码

# PowerShell
$env:NODE_ENV="development"; yarn db:migrate

看到一连串「migrated」输出即迁移完成。注意这里用的是 development 而不是 production（原因详见坑 3）。

4.5 构建

bash 复制代码

yarn build

过程：前端构建（约 2 分钟）→ 国际化资源 → 服务端编译。Windows 下最后「复制静态文件」阶段会报错退出，属已知问题，手动补一下即可：

bash 复制代码

# 把各插件的 plugin.json 复制到构建目录
python -c "import os, shutil; [shutil.copy2(f'plugins/{p}/plugin.json', f'build/plugins/{p}/plugin.json') for p in os.listdir('plugins') if os.path.isfile(f'plugins/{p}/plugin.json')]"

4.6 启动服务

bash 复制代码

yarn start

启动日志依次出现 collaboration → websockets → worker → web 服务，最后一行：

bash 复制代码

Listening on http://localhost:3000 / http://127.0.0.1:3000

浏览器打开 http://127.0.0.1:3000，看到「创建工作区」引导页即部署成功。

💡 如果服务器/电脑装了 Docker，官方也提供了更省事的 Docker 方式（compose 管理 outline + postgres + redis 三个容器，镜像为 docker.getoutline.com/outlinewiki/outline），详见官方自托管文档 docs.getoutline.com/s/hosting。本文聚焦 Windows 源码部署是因为它不依赖 Docker、对本地环境更友好。

五、使用详解

场景 1：初始化------创建工作区

首次打开会进入「创建工作区」表单：填写工作区名称（如「我的知识库」）、管理员名称、管理员邮箱，点「继续操作」。第一个用户自动成为管理员，创建完成后直接进入主页，无需额外登录步骤。

场景 2：写第一篇文档

主页右上角「新建文档」→ 进入编辑器。直接输入内容，支持 Markdown 快捷输入（如输入「/」呼出插入菜单）。内容自动保存，左侧可查看目录，右上角可分享或发布。

场景 3：用文档集组织内容

侧边栏「文档集」是 Outline 的组织核心：可以按部门/项目/主题建立多个文档集，每个文档集单独设置成员权限。点击「新建文档集」→ 输入名称 → 创建；写好的文档点右上角「发布」→ 选择文档集，就归入对应分类。

场景 4：搜索内容

顶部搜索框（快捷键 Ctrl+K）支持全文搜索，可按文档集、作者、时间过滤。命中结果会显示文档标题与更新时间。

⚠️ 两个使用注意：① 文档要「发布」后才能被搜索到（草稿默认不进搜索）；② 中文搜索按「前缀」匹配------搜句子开头的部分（如「欢迎使用」）能命中，搜句子中间的词（如「知识库」独立出现时）可能搜不到。重要文档建议把关键词放在标题或段落开头。

场景 5：登录与邀请成员

需要重新登录或邀请同事时，走「邮箱魔法链接」流程：

打开登录页 → 点「使用电子邮箱继续」→ 输入邮箱 → 点「登录」：

然后到邮箱里找到 Outline 发来的邮件，点邮件里的登录链接（或输入邮件中的验证码），即完成登录。邀请同事也是一样：同事在自己电脑上打开同一地址、输入自己的邮箱，就能收到登录链接加入。

六、踩坑记录与解决方案

坑 1：数据库服务后台启动异常

现象：从某些自动化工具/受限终端启动 PostgreSQL 后，主进程正常但连接时崩溃（日志出现 0xC0000142 异常），连接被拒绝。

原因：受限进程令牌下，PostgreSQL 创建后端进程时 DLL 初始化失败。

解决：改用标准的 PowerShell/cmd 窗口启动；长期使用建议注册为 Windows 服务（pg_ctl register），用系统账户运行最稳定。

坑 2：报错「The server does not support SSL connections」

现象：生产模式启动后连接数据库报 SSL 错误。

原因：生产模式默认要求数据库连接启用 SSL，本地数据库通常没开。

解决：.env 中加 PGSSLMODE=disable（数据库与服务在同一台机器时官方也建议这样配置）。

坑 3：迁移命令的两个「配置档」问题

现象：yarn db:migrate 直接跑报 SSL 错误；用带「ssl-disabled」的配置档跑，部分迁移脚本又报环境校验失败。

原因：迁移命令按 NODE_ENV 选择数据库连接配置（production 强制 SSL），而自定义迁移脚本还要求标准的运行环境标识。

解决：迁移时使用 $env:NODE_ENV="development"; yarn db:migrate（development 连接配置同样不带 SSL，且环境校验通过）。迁移内容与运行模式无关，迁移完再以生产模式启动即可。

坑 4：SMTP_FROM_EMAIL 格式校验

现象：启动/迁移报「SMTP_FROM_EMAIL must be a valid email address」。

原因：内部校验要求标准邮箱格式。

解决：发件地址必须是完整邮箱格式（如 name@example.com），「@localhost」这类内部名不合法。

坑 5：Windows 构建到「复制静态文件」阶段失败

现象：yarn build 接近完成时，在复制插件清单阶段报错退出。

原因：构建脚本使用了 Linux 风格的复制命令，Windows 命令行不兼容。

解决：主产物此时已生成，只需手动补齐复制（见 4.5 节的 Python 一行命令），即可继续启动。

坑 6：Windows 下插件全部未加载（搜索/邮件静默失效）

现象：服务能启动、文档能保存，但搜索报错、邮件功能不工作------排查发现所有插件都没加载（构建目录下明明有插件文件）。

原因：插件加载器用 path.join 生成文件匹配模式，在 Windows 上会生成反斜杠路径，而匹配库只能识别正斜杠------结果一个文件都匹配不到。这是平台级兼容 bug。

解决：给加载器的匹配调用加上 windowsPathsNoEscape: true 选项（见 4.3 修复一），修改后 9 个插件正常加载，搜索与邮件功能全部恢复。

坑 7：中文搜索搜不到？先了解它的匹配机制

现象：文档明明含「部署」两个字，搜「部署」却搜不到；搜「欢迎使用」能命中。

原因：搜索基于 PostgreSQL 全文检索，其默认分词器不切分中文------整句中文被当作一个大词条，只能从词条开头做前缀匹配。

解决：搜索时用句子开头的词组；写作时把关键词放在标题或段落开头。进阶玩家可在 PostgreSQL 安装中文分词扩展（zhparser）彻底解决。

坑 8：草稿搜不到

现象：刚写的文档搜索不到。

原因：草稿（未发布）默认不进公共搜索。

解决：在文档页点「发布」选择文档集后即可被搜索到。

七、部署验证

部署完成后，主页效果如下（含侧边栏、文档集、文档列表）：

核心功能逐项验证结果：

功能	运行结果
服务启动	启动输出 Listening on :3000，健康检查接口返回 200，界面为中文
工作区创建	表单提交即完成，首个用户自动成为管理员
文档编辑	标题/正文实时保存，自动记录版本
文档集	创建成功并显示在侧边栏，可归组文档
发布文档	发布到指定文档集成功，随即进入搜索索引
全文搜索	前缀匹配命中已发布文档（机制见坑 7）
邮件登录	登录邮件正常发出（含登录链接与验证码），按链接登录成功

八、常见问题

Q1：必须有服务器才能用吗？

不是。本文方案在普通 Windows 电脑上即可运行。想让局域网内同事访问，把 .env 的 URL 换成电脑的局域网 IP 即可；想让公网访问，需要一台有公网 IP 的服务器 + 域名 + HTTPS（官方有 SSL 配置文档）。

Q2：不配 SMTP 行不行？

不行（生产模式下）。Outline 的登录依赖邮件魔法链接，没有 SMTP 就没有登录方式。SMTP 用任意邮箱的授权码即可，配置一次长期有效。

Q3：数据存在哪里？怎么备份？

两块：PostgreSQL 数据库（文档与账号数据）+ FILE_STORAGE 指定目录（附件）。备份 = 导出数据库 + 复制附件目录（官方有专门的备份文档）。

Q4：怎么升级到新版本？

源码方式：git pull → yarn install → 执行数据库迁移 → 重新 build → 重启服务。升级前记得先备份。

Q5：能导入 Notion/语雀的内容吗？

支持导入 Markdown、HTML、docx 等格式的 zip 包（侧边栏有「导入」入口），Mastodon/Notion 等也有对应导出转换路径，按官方导入文档操作即可。

九、总结

Outline 是自托管知识库领域最成熟的方案之一：41k Star、功能完整（协作/权限/搜索/版本历史）、中文界面友好，把「团队 Wiki + 个人知识库」两件事用一套系统解决。整套部署的核心是四件套环境（Node + PostgreSQL + Redis + SMTP），加上 Windows 下的两处平台修复，其余就是标准流程。

部署路径建议：Windows 本地/内网 → 本文源码部署方案；服务器已有 Docker → 官方 Docker 方式（compose 一条命令）。数据安全上不要偷懒：定期备份数据库与附件目录。

如果部署过程遇到本文没覆盖的问题，欢迎评论区交流。你的知识库第一篇文章会写什么？

完整命令速查

bash 复制代码

# ===== 环境验证 =====
node -v
psql\bin\psql.exe -U outline -h 127.0.0.1 -d outline -c "SELECT 1;"
redis-cli.exe ping

# ===== PostgreSQL 初始化（仅首次）=====
pgsql\bin\initdb.exe -D pgdata -U postgres -A trust -E UTF8 --no-locale
pgsql\bin\pg_ctl.exe -D pgdata -l pglog.txt start
pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -c "CREATE USER outline WITH PASSWORD 'outline_pass' SUPERUSER;"
pgsql\bin\psql.exe -U postgres -h 127.0.0.1 -c "CREATE DATABASE outline OWNER outline;"

# ===== Redis 启动 =====
redis-server.exe --port 6379

# ===== 获取源码与依赖 =====
git clone https://github.com/outline/outline.git
cd outline
yarn config set npmRegistryServer https://registry.npmmirror.com
yarn install

# ===== 迁移（development 配置档）=====
$env:NODE_ENV="development"; yarn db:migrate

# ===== 构建 =====
yarn build
# Windows 手动补插件清单复制：
# python -c "import os, shutil; [shutil.copy2(f'plugins/{p}/plugin.json', f'build/plugins/{p}/plugin.json') for p in os.listdir('plugins') if os.path.isfile(f'plugins/{p}/plugin.json')]"

# ===== 启动 =====
yarn start
# 浏览器访问 http://127.0.0.1:3000

# ===== 生成密钥（写 .env 用）=====
python -c "import secrets; print(secrets.token_hex(32))"

项目地址： $Outline$ (https://github.com/outline/outline)

标签：Outline | 自托管 | 知识库 | Notion替代 | PostgreSQL | 部署教程 | 开源软件 | Windows教程