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

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 即可。部署过程中你会直接接触的就是这五样技术栈对照方便你心里有个底层技术部署时你接触它的场景前端React 17 MobX styled-components纯浏览器端部署不关心编辑器ProseMirror YjsHocuspocus实时协作走 WebSocket反代要放行后端Node.js Koa TypeScript跑在outlinewiki/outline官方镜像里数据库PostgreSQLSequelize ORM建库、迁移、备份都围着它转缓存/队列RedisBull 队列邮件、导入导出等异步任务靠它容器Docker Docker Compose编排三个服务的唯一入口注意一个细节官方镜像启动时会同时跑 web、worker、collaboration、websockets 四类进程仓库里 docs/SERVICES.md 有说明单机部署不需要拆进程把这点记下来后面排错会用到。动手前的三张清单逐项打勾把准备工作压成三张表每项都确认过再往下走能省掉大半装完跑不起来的时间。硬件清单团队规模CPU内存磁盘 50 人2 核4GB50GB SSD50–200 人4 核8GB100GB SSD 200 人8 核16GB200GB SSD内存是瓶颈所在Node 进程 PostgreSQL 都吃内存磁盘务必用 SSD附件上传和查询都会明显受益。软件清单Docker Engine ≥ 20.10Compose v2docker compose version验证Git仅用于拉源码看配置Ubuntu 20.04 / CentOS 8或同系发行版不需要在服务器上装 Node.js——用官方镜像Node 运行时在容器里端口清单部署前逐项打勾端口组件暴露方式443Nginx唯一对外HTTPS3000Outline 容器仅反代可访问不映射到宿主机5432PostgreSQL只绑127.0.0.16379Redis只绑127.0.0.1仓库自带的 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_ENVproduction URLhttps://wiki.yourcompany.com PORT3000 SECRET_KEYopenssl rand -hex 32 的生成结果 UTILS_SECRET另一串随机值 DATABASE_URLpostgres://user:passpostgres:5432/outline REDIS_URLredis://redis:6379 SMTP_HOSTsmtp.yourcompany.com SMTP_PORT587 SMTP_USERNAMEnotifyyourcompany.com SMTP_PASSWORDyour_smtp_pass SMTP_FROM_EMAILnotifyyourcompany.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: - URLhttps://wiki.yourcompany.com - DATABASE_URLpostgres://user:passpostgres:5432/outline - REDIS_URLredis://redis:6379 - SECRET_KEY${SECRET_KEY} - UTILS_SECRET${UTILS_SECRET} - SMTP_HOSTsmtp.yourcompany.com - SMTP_PORT587 - SMTP_USERNAMEnotifyyourcompany.com - SMTP_PASSWORD${SMTP_PASSWORD} - SMTP_FROM_EMAILnotifyyourcompany.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、会话签名都建立在可信域名之上。Lets 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_IDyour_client_id OIDC_CLIENT_SECRETyour_client_secret OIDC_AUTH_URIhttps://sso.yourcompany.com/authorize OIDC_TOKEN_URIhttps://sso.yourcompany.com/token OIDC_USERINFO_URIhttps://sso.yourcompany.com/userinfo OIDC_LOGOUT_URIhttps://sso.yourcompany.com/logout OIDC_DISPLAY_NAME公司SSO接上 SSO 后建议关掉邮箱注册在管理后台关闭允许用户自行注册账号生命周期就完全由你的身份系统管了。第三层细化权限。登录体系稳了之后再做这层按部门建 Collection知识库空间用组的权限可读/可写/可管理控制谁能进哪个空间对外分享走 Share 功能生成的只读链接而不是把整个域名开给访客。权限是逐 Collection 下发的所以这一步放最后——身份没接好之前调权限等于在流沙上画图。让数据库别成为瓶颈先查再改后加 CDN性能调优的纪律是先用数据说话别一上来就调参数。顺序是三步先查瓶颈。看 Outline 日志里有没有慢操作再看 PostgreSQL 侧的表统计全表扫描多不多、连接数是否顶格。大部分慢最后都指向两件事连接池配太小或work_mem小到排序走磁盘。再调参数。确认瓶颈后只改这几个改一个观察一周参数起点建议位置shared_buffers物理内存的 1/4postgresql.confeffective_cache_size物理内存的 3/4postgresql.confwork_mem16–64MB按并发调postgresql.confmax_connections≥ 100postgresql.confDATABASE_CONNECTION_POOL_MAX与上条配套全进程总和别超.envRedis 这边有个反直觉的坑它同时扛着 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_IDyour_client_id SLACK_CLIENT_SECRETyour_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 到处塞。工具和通知都通了系统进入日常运行状态。接下来是把踩过的坑收拢成一张表。 常见卡点速查从症状到一条命令症状最可能的原因一条命令定位页面打不开 / 502outline 容器没起或健康检查未过docker compose ps docker compose logs -f outline能打开但登录反复跳转.env的URL与实际域名/协议不一致grep ^URL .env多人同编不同步、编辑卡顿反代没放行/ws与/collaboration或 Redis 断连docker compose exec redis redis-cli ping邀请邮件收不到SMTP 认证或端口错误docker compose logs outline \| grep -i smtp图片附件裂图附件卷权限或挂载丢失docker compose exec outline ls -ld /var/lib/outline/data整体响应变慢连接池不足或全表扫描curl -s https://wiki.yourcompany.com/_health先看服务存活再查慢查询排错顺序永远是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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考