Outline Wiki私有化部署

本文主要记录在 Docker 环境中私有化部署 Outline 知识库的过程：准备 PostgreSQL / Redis、配置环境变量、对接 GitLab OIDC，以及启动后的基本验证要点。

官方托管说明入口：Hosting Outline。下文以单机 Docker（含 Unraid 类面板生成的 docker run）为例；密钥、内网地址与 OAuth 客户端信息一律使用占位符，不要把真实 SECRET_KEY / 数据库密码写进仓库或截图。

背景说明

Outline 依赖：

PostgreSQL（业务库）
Redis（队列/协作相关）
对象存储或本地目录（附件）
至少一种登录方式（本文使用 OIDC → GitLab）

反向代理负责 HTTPS 时，应用侧常设 FORCE_HTTPS=false，由入口做 TLS 终结。

环境信息

项目	取值（示例 / 占位）
运行方式	Docker，`docker.getoutline.com/outlinewiki/outline:latest`
网络	示例使用 `host` 网络；亦可 bridge + 端口映射
应用端口	`3002`（与反代上游一致即可）
数据库	PostgreSQL `@<db-host>:5432`，库名/用户 `outline`
缓存	Redis `@<redis-host>:6379`
附件	`FILE_STORAGE=local`，宿主机目录挂载到容器 `/var/lib/outline/data`
公网 URL	`https://<outline-host>`
IdP	GitLab OIDC（`https://<gitlab-host>`）

CPU 绑核、pids 限制等为宿主机调度优化，可按机器裁剪，非 Outline 功能必需。

准备工作

生成密钥

openssl rand -hex 32

将输出分别用于 SECRET_KEY 与 UTILS_SECRET（各生成一次，不要复用同一串到所有环境）。

准备 PostgreSQL

使用管理员账号连接后创建库与用户（密码换强口令）：

psql -h <db-host> -p 5432 -U <admin-user> -d postgres

CREATE DATABASE outline;
CREATE USER outline WITH PASSWORD '<password>';
ALTER DATABASE outline OWNER TO outline;
-- 或按最小权限模型 GRANT，此处从简

确认应用连接串形如：

postgresql://outline:<password>@<db-host>:5432/outline

若 Postgres 与 Docker 之间不走 SSL，可设 PGSSLMODE=disable（仅限可信网络）。

准备 Redis

保证 Outline 能访问：

redis://<redis-host>:6379

若 Redis 有密码或 Sentinel，按 ioredis URL / 官方文档组装 REDIS_URL。

准备 GitLab OIDC 应用

在 GitLab 创建 OAuth Application / OIDC 客户端（界面以 GitLab 版本为准）：

Redirect URI：https://<outline-host>/auth/oidc.callback（以 Outline 当前文档为准，部署前核对官方路径）
记录 Application ID → OIDC_CLIENT_ID
记录 Secret → OIDC_CLIENT_SECRET
授权范围需覆盖 openid profile email（与 OIDC_SCOPES 一致）

历史环境曾保留配置界面截图于本地 assets；公开稿以文字步骤为准，避免把真实 Client ID 打进图床。

配置服务

环境变量要点

最小相关集合（完整官方模板见 Outline 仓库 .env.sample，下列为部署时用到的核心项）：

NODE_ENV=production
SECRET_KEY=<secret>
UTILS_SECRET=<utils-secret>

DATABASE_URL=postgresql://outline:<password>@<db-host>:5432/outline
PGSSLMODE=disable
REDIS_URL=redis://<redis-host>:6379

URL=https://<outline-host>
PORT=3002
FORCE_HTTPS=false

FILE_STORAGE=local
FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data
FILE_STORAGE_UPLOAD_MAX_SIZE=262144000

DEFAULT_LANGUAGE=zh_CN
LOG_LEVEL=info

OIDC_CLIENT_ID=<client-id>
OIDC_CLIENT_SECRET=<client-secret>
OIDC_AUTH_URI=https://<gitlab-host>/oauth/authorize
OIDC_TOKEN_URI=https://<gitlab-host>/oauth/token
OIDC_USERINFO_URI=https://<gitlab-host>/oauth/userinfo
OIDC_DISPLAY_NAME=GitLab
OIDC_SCOPES=openid profile email
# 用户名 claim 依 GitLab/JWT 载荷调整；错误配置会导致登录用户名异常
OIDC_USERNAME_CLAIM=preferred_username

说明：

原稿曾出现 OIDC_USERNAME_CLAIM=root，这更像误配；GitLab 常见为 preferred_username 或 nickname，以实际 userinfo/JWT 字段为准（待确认）。
FORCE_HTTPS：反代已做 HTTPS 且传到容器为 HTTP 时，按官方说明关闭应用内强制跳转，避免重定向环。
LOG_LEVEL=silly 仅排障时短期开启，生产建议 info 或 warn。

Docker 启动示例

将密钥与地址替换后启动（示意；勿提交真实环境变量到 git）：

docker run -d \
  --name outline \
  --restart unless-stopped \
  -e NODE_ENV=production \
  -e SECRET_KEY='<secret>' \
  -e UTILS_SECRET='<utils-secret>' \
  -e DATABASE_URL='postgresql://outline:<password>@<db-host>:5432/outline' \
  -e REDIS_URL='redis://<redis-host>:6379' \
  -e FILE_STORAGE=local \
  -e FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data \
  -e PORT=3002 \
  -e PGSSLMODE=disable \
  -e LOG_LEVEL=info \
  -e DEFAULT_LANGUAGE=zh_CN \
  -e URL='https://<outline-host>' \
  -e FORCE_HTTPS=false \
  -e OIDC_AUTH_URI='https://<gitlab-host>/oauth/authorize' \
  -e OIDC_TOKEN_URI='https://<gitlab-host>/oauth/token' \
  -e OIDC_USERINFO_URI='https://<gitlab-host>/oauth/userinfo' \
  -e OIDC_USERNAME_CLAIM='preferred_username' \
  -e OIDC_DISPLAY_NAME='GitLab' \
  -e OIDC_SCOPES='openid profile email' \
  -e OIDC_CLIENT_ID='<client-id>' \
  -e OIDC_CLIENT_SECRET='<client-secret>' \
  -p 3002:3002 \
  -v /path/on/host/outline-data:/var/lib/outline/data:rw \
  docker.getoutline.com/outlinewiki/outline:latest

若使用 network_mode=host，则去掉 -p，并保证宿主机 PORT 未被占用。Unraid 等面板生成的 label、时区、cpuset 可按平台保留。

数据目录需可写：

mkdir -p /path/on/host/outline-data
# 权限按容器运行用户调整，无法写入时附件上传会失败

反向代理

将 https://<outline-host> 反代到 http://127.0.0.1:3002（或 host 网络下的对应地址），并配置 WebSocket（若协作功能需要，按 Outline 当前文档开启）。TLS 证书在反代终止。

启动和验证

docker ps --filter name=outline
docker logs --tail 100 outline

期望容器持续运行，日志无数据库/Redis 连接失败循环。

浏览器访问 https://<outline-host>：

出现 GitLab（OIDC）登录入口
授权后回到 Outline，用户信息正常
创建测试文档、上传小附件，确认本地存储目录有文件生成

数据库侧可复查：

psql -h <db-host> -U outline -d outline -c '\dt'

有业务表且无持续迁移错误即基本正常。

常见问题

现象	可能原因
登录回调 4xx/5xx	Redirect URI 与 GitLab 应用不一致；`URL` 与真实访问域名不一致
用户名异常或无法建用户	`OIDC_USERNAME_CLAIM` 与 IdP 字段不匹配
附件失败	本地目录权限；`FILE_STORAGE_*` 路径未挂载
重定向死循环	`FORCE_HTTPS` 与反代 TLS 语义冲突
无法连库	`DATABASE_URL`、防火墙、`pg_hba.conf`、SSL 模式

注意事项

所有密钥轮换后需重建/更新容器环境变量并重启。
latest 标签便于试用，生产建议钉版本号并做升级前备份（Postgres + 附件目录）。
日志级别 silly/debug 可能带出请求细节，排障后改回。
本文不包含 SMTP、S3、多协作节点拆分等进阶项；需要时对照官方 SERVICES / 环境变量文档。

参考资料

Outline Hosting 文档
Outline 项目仓库
GitLab：OAuth 应用 / OpenID Connect 文档（按自建 GitLab 版本查阅）

背景说明#

环境信息#

准备工作#

生成密钥#

准备 PostgreSQL#

准备 Redis#

准备 GitLab OIDC 应用#

配置服务#

环境变量要点#

Docker 启动示例#

反向代理#

启动和验证#

常见问题#

注意事项#

参考资料#