企业官网建设流程全解析

Outline 自托管部署实战：一台空服务器到团队知识库上线

【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址: https://gitcode.com/GitHub_Trending/ou/outline

想象一下这个场景：产品把需求文档放在 A 工具，设计稿说明在 B 工具，研发的技术决策记录散在聊天窗口里。开评审会时大家互相甩链接，最后没人说得清哪份才是"最新版本"。这类知识碎片化的问题，靠自觉解决不了，靠的是把文档收敛到一个所有人都在用的地方——这正是 Outline 想解决的事。Outline 是一个开源知识库项目，前端 React、后端 Node.js，编辑器基于 ProseMirror 实现实时协同编辑，数据落在 PostgreSQL 里。自托管部署它并不复杂：一套 Docker Compose、两个依赖容器，跑起来就是一个团队共用的知识库。

30 秒选型：部署时你会碰到哪几个组件

一句话结论：Outline 本体是一个容器，它强依赖 PostgreSQL 和 Redis，对外只暴露 3000 端口，前面垫一层 Nginx 即可。部署过程中你会直接接触的就是这五样：

技术栈对照，方便你心里有个底：

注意一个细节：官方镜像启动时会同时跑 web、worker、collaboration、websockets 四类进程（仓库里 docs/SERVICES.md 有说明），单机部署不需要拆进程，把这点记下来，后面排错会用到。

动手前的三张清单，逐项打勾

把准备工作压成三张表，每项都确认过再往下走，能省掉大半"装完跑不起来"的时间。

硬件清单

内存是瓶颈所在：Node 进程 + PostgreSQL 都吃内存，磁盘务必用 SSD，附件上传和查询都会明显受益。

软件清单

• Docker Engine ≥ 20.10，Compose v2（docker compose version验证）
• Git，仅用于拉源码看配置
• Ubuntu 20.04+ / CentOS 8+（或同系发行版）
• 不需要在服务器上装 Node.js——用官方镜像，Node 运行时在容器里

端口清单：部署前逐项打勾

仓库自带的 docker-compose.yml 就是这种"数据库只绑回环地址"的写法，照抄这个习惯就行。5432 和 6379 一旦暴露公网，扫描器几天内就会找到。

六步走：从克隆到可访问的页面

清单确认后开始动手。整体节奏：克隆 → 配.env→ 写 Compose → 启动 → 迁移数据库 → 上反代开账号。

第 1 步：拿代码。仓库本身主要用来查看配置和源码，生产环境跑官方镜像。

git clone https://gitcode.com/GitHub_Trending/ou/outline cd outline

第 2 步：配环境变量。仓库里有完整的变量清单 .env.sample，先复制再改，比手敲全得多：

cp .env.sample .env

必改的几项，其余保持注释或默认：

NODE_ENV=production URL=https://wiki.yourcompany.com PORT=3000 SECRET_KEY=<openssl rand -hex 32 的生成结果> UTILS_SECRET=<另一串随机值> DATABASE_URL=postgres://user:pass@postgres:5432/outline REDIS_URL=redis://redis:6379 SMTP_HOST=smtp.yourcompany.com SMTP_PORT=587 SMTP_USERNAME=notify@yourcompany.com SMTP_PASSWORD=your_smtp_pass SMTP_FROM_EMAIL=notify@yourcompany.com

这里有个坑：SECRET_KEY和UTILS_SECRET必须是 32 字节随机值，且生成后要妥善保存——它们分别负责会话签名和文件密钥，丢了意味着所有登录态失效、附件解不开。URL必须和最终访问域名一字不差，后面登录跳转全靠它。

第 3 步：写 Compose。在仓库自带的 postgres/redis 基础上补一个 outline 服务：

services: postgres: image: postgres:14 ports: ["127.0.0.1:5432:5432"] environment: POSTGRES_USER: user POSTGRES_PASSWORD: pass POSTGRES_DB: outline volumes: [postgres-data:/var/lib/postgresql/data] redis: image: redis:7 ports: ["127.0.0.1:6379:6379"] volumes: [redis-data:/data] outline: image: outlinewiki/outline depends_on: [postgres, redis] environment: - URL=https://wiki.yourcompany.com - DATABASE_URL=postgres://user:pass@postgres:5432/outline - REDIS_URL=redis://redis:6379 - SECRET_KEY=${SECRET_KEY} - UTILS_SECRET=${UTILS_SECRET} - SMTP_HOST=smtp.yourcompany.com - SMTP_PORT=587 - SMTP_USERNAME=notify@yourcompany.com - SMTP_PASSWORD=${SMTP_PASSWORD} - SMTP_FROM_EMAIL=notify@yourcompany.com volumes: [outline-data:/var/lib/outline/data] restart: always volumes: {postgres-data: {}, redis-data: {}, outline-data: {}}

SERVICES不设也行，默认就包含全部四类进程；只有把协作服务拆到别的机器时才需要显式配置。附件目录挂在/var/lib/outline/data，和官方 Dockerfile 里的卷定义一致，升级重建容器后文件不丢。

第 4 步：启动。

docker compose up -d docker compose ps # 三个容器都 healthy 再继续

镜像自带的健康检查探的是/_health接口，ps里看状态比翻日志快。

第 5 步：迁移数据库。第一次启动不会自动建表：

docker compose exec outline yarn db:migrate

之后每次升级版本都要再跑一次这条命令，养成"升级=拉镜像+migrate+重启"的肌肉记忆。

第 6 步：Nginx 反代 + 开管理员账号。配置核心就三块：静态缓存、WebSocket 升级、常规转发：

server { listen 443 ssl http2; server_name wiki.yourcompany.com; ssl_certificate /etc/nginx/ssl/wiki.crt; ssl_certificate_key /etc/nginx/ssl/wiki.key; location /ws/ { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } location /collaboration/ { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; } location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

/ws和/collaboration这两个前缀是实时协作的通道，漏了的话页面能打开，但多人同编会变成"各自为战"。nginx -s reload之后打开https://wiki.yourcompany.com，第一个注册的用户自动成为管理员，团队名、成员邀请都从这里发起。

跑通到这里，系统已经在服务真实流量了。但还差最关键的一件事：默认状态下它只是"能访问"，不是"安全"。

🔒 上线后：先锁传输，再接身份，最后收权限

安全配置按依赖关系排序做，别三件混着来。

第一层：锁死传输链路。没有 HTTPS 一切免谈，因为登录 Cookie、会话签名都建立在可信域名之上。Let's Encrypt 十分钟搞定：

apt install certbot python3-certbot-nginx certbot --nginx -d wiki.yourcompany.com

同时确认.env里的URL已经是 https 地址，然后重启容器——这个坑下面速查表里还会再出现一次。

第二层：接入公司身份系统。当前版本走 OIDC / OAuth 体系（Google、Slack、GitHub 登录和通用 OIDC 都内置），在.env里填供应商参数，重启容器即生效，不需要改代码：

OIDC_CLIENT_ID=your_client_id OIDC_CLIENT_SECRET=your_client_secret OIDC_AUTH_URI=https://sso.yourcompany.com/authorize OIDC_TOKEN_URI=https://sso.yourcompany.com/token OIDC_USERINFO_URI=https://sso.yourcompany.com/userinfo OIDC_LOGOUT_URI=https://sso.yourcompany.com/logout OIDC_DISPLAY_NAME=公司SSO

接上 SSO 后建议关掉邮箱注册（在管理后台关闭"允许用户自行注册"），账号生命周期就完全由你的身份系统管了。

第三层：细化权限。登录体系稳了之后再做这层：按部门建 Collection（知识库空间），用组的权限（可读/可写/可管理）控制谁能进哪个空间；对外分享走 Share 功能生成的只读链接，而不是把整个域名开给访客。权限是逐 Collection 下发的，所以这一步放最后——身份没接好之前调权限，等于在流沙上画图。

让数据库别成为瓶颈：先查，再改，后加 CDN

性能调优的纪律是：先用数据说话，别一上来就调参数。顺序是三步：

先查瓶颈。看 Outline 日志里有没有慢操作，再看 PostgreSQL 侧的表统计（全表扫描多不多、连接数是否顶格）。大部分"慢"最后都指向两件事：连接池配太小，或work_mem小到排序走磁盘。

再调参数。确认瓶颈后，只改这几个，改一个观察一周：

Redis 这边有个反直觉的坑：它同时扛着 Bull 队列和协作状态，不要直接上maxmemory-policy allkeys-lru——LRU 淘汰会把排队的任务（发邮件、导文档）悄悄丢掉。正确姿势是留足maxmemory上限、策略保持noeviction，队列宁可阻塞不可丢。

最后加 CDN。用户多到跨地域访问时，在.env设置CDN_URL指向你的 CDN 域名，静态资源的 JS/CSS/图片路径会自动改走 CDN，源站只剩 API 和 WebSocket。前两步没做之前加 CDN 只是把慢换到另一个慢。

数据兜底：备份、归档、恢复要跑成闭环

只备份不验证，等于没备份。整条链路串起来是：每天备份 → 滚动归档 → 定期恢复演练。

#!/bin/bash # backup.sh：每天由 cron 调用 DATE=$(date +%Y%m%d-%H%M) BACKUP_DIR=/var/backups/outline mkdir -p $BACKUP_DIR docker compose exec -T postgres pg_dump -U user outline > $BACKUP_DIR/outline-$DATE.sql gzip $BACKUP_DIR/outline-$DATE.sql find $BACKUP_DIR -name "outline-*.sql.gz" -mtime +14 -delete # 滚动保留 14 天

# crontab：每天凌晨 3 点 0 3 * * * /path/to/backup.sh

别忘了附件卷：数据库里没有图片本体，/var/lib/outline/data对应的outline-data卷要一并 rsync 到异地。恢复演练每季度做一次，用备份恢复到临时实例而不是直接灌生产：

gunzip -c /var/backups/outline-20260101-0300.sql.gz \ | docker compose exec -T postgres psql -U user -d outline

第一次演练时顺手确认两件事：备份文件能不能解开、恢复后随机翻两篇文档内容是否完整。能做到这点，"删库"这个最坏的假设就从灾难降级成了麻烦。

把你已有的工具链接进 Outline

部署完成后的价值不在"多了一个网站"，而在于它嵌进团队现有工作流的速度。两条主线：

IM 通知与集成。仓库的 plugins/ 目录里 Slack、Discord、GitHub、GitLab 等都是现成插件，多数只需在.env里填凭据，重启容器即可：

SLACK_CLIENT_ID=your_client_id SLACK_CLIENT_SECRET=your_client_secret

接上后，文档 @ 了某个 Slack 频道、GitHub 里引用了某篇文档，两边都会出现入口。选哪个插件取决于你们团队每天泡在哪个 IM 里——接"用得多"的那个，而不是"功能全"的那个。

REST API。想把 Outline 当数据源（比如接入内部搜索、自动生成周报），用管理后台生成的 API Key 直接打接口，最小示例：

const res = await fetch("https://wiki.yourcompany.com/api/documents", { method: "POST", headers: { Authorization: "Bearer your_api_key", "Content-Type": "application/json", }, body: JSON.stringify({ title: "会议纪要 2026-08-31", text: "## 决议\n- 知识库统一到 Outline", collectionId: "col_xxxxxxxxxx", }), }); const doc = await res.json();

API Key 有权限级别，按"最小够用"生成，别拿 admin 级的 key 到处塞。

工具和通知都通了，系统进入日常运行状态。接下来是把踩过的坑收拢成一张表。

🧯 常见卡点速查：从症状到一条命令

排错顺序永远是：ps看容器 → 健康接口 → 日志 → 依赖服务（Redis/PG）。/_health返回 OK 而功能异常，问题基本就在配置层而不是进程层。

部署不消失：30/60/90 天的运营清单

系统上线只是起点，知识库的寿命取决于之后怎么用。给你一份陪跑式清单，不用一次做完：

• 第 30 天：让人用起来。组织一次 30 分钟的使用培训（重点是搜索和模板），把散落在旧工具里的历史文档导入进来；接通至少一个 IM 集成。这一步的判据很简单：一周内有没有新文档被自然创建。
• 第 60 天：让内容治理起来。给每个 Collection 指定负责人，约定文档过期归档机制；完成 SSO 接入并关闭开放注册；做第一次恢复演练，验证备份真的能救命。
• 第 90 天：让系统持续变好。跑一轮性能审计（慢查询、WEB_CONCURRENCY是否该随核数上调）；制定版本升级节奏——拉新镜像、yarn db:migrate、重启，整个流程应该已经是你闭眼能做的程度了。

三个月后回头看，如果团队提到"查资料"第一反应是打开这个域名，这套自托管知识库才算真正立住了。

【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址: https://gitcode.com/GitHub_Trending/ou/outline