Outline 是适合团队内部文档、产品手册和技术知识库的开源 Wiki。它的搜索、Markdown 编辑、权限和版本历史比简单的文件目录更适合长期协作，但生产部署至少需要 PostgreSQL、Redis、对象存储（或本地附件目录）和 HTTPS。本文以 Ubuntu 24.04、Docker Compose 和一个独立域名为例，从零部署一套可维护的 Outline。
Outline 页面本身不算重，真正占资源的是 PostgreSQL、Redis、全文搜索和附件处理。小团队可以按下面的起点规划：
| 场景 | 建议配置 | 说明 |
|---|---|---|
| 个人测试 | 2 核 2GB、40GB SSD | 只放少量文档，不建议承载团队生产 |
| 5-20 人团队 | 2-4 核 4GB、80GB SSD | PostgreSQL、Redis 和 Outline 同机 |
| 20 人以上 | 4 核 8GB、160GB+ NVMe | 数据库和附件建议独立备份或拆机 |
如果 VPS 只有 1GB 内存，先完成 VPS 低内存 ZRAM 和 Swap 优化，再部署 Outline。Swap 只能缓解启动峰值，不能替代长期所需的内存。
将 docs.example.com 的 A/AAAA 记录解析到 VPS，安装 Docker Compose：
sudo apt update
sudo apt install -y ca-certificates curl openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/outline/{data,postgres,redis}
sudo chown -R "$USER":"$USER" /opt/outline
cd /opt/outline
只开放 SSH、80 和 443。PostgreSQL 的 5432、Redis 的 6379 不要映射到公网。
Outline 至少需要 SECRET_KEY 与 UTILS_SECRET。使用随机值，不要复制网上示例：
openssl rand -hex 32
openssl rand -hex 32
创建 .env：
URL=https://docs.example.com
PORT=3000
FORCE_HTTPS=true
SECRET_KEY=替换为第一条随机值
UTILS_SECRET=替换为第二条随机值
DATABASE_URL=postgres://outline:替换数据库密码@postgres:5432/outline
REDIS_URL=redis://redis:6379
POSTGRES_USER=outline
POSTGRES_PASSWORD=替换数据库密码
POSTGRES_DB=outline
# OAuth 以 GitHub 为例，生产环境应使用组织级 OAuth App
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
OIDC_AUTH_URI=
OIDC_TOKEN_URI=
OIDC_USERINFO_URI=
OIDC_LOGOUT_URI=
OIDC_USERNAME_CLAIM=preferred_username
OIDC_DISPLAY_NAME=公司账号
Outline 不适合直接开放“任意注册”。没有接入 OAuth 时，先把站点放在 VPN、访问控制或临时测试环境内。
创建 compose.yml：
services:
outline:
image: outlinewiki/outline:latest
container_name: outline
restart: unless-stopped
env_file: .env
command: sh -c "yarn sequelize:migrate --env production-ssl-disabled && yarn start"
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
ports:
- "127.0.0.1:3000:3000"
volumes:
- ./data:/var/lib/outline/data
postgres:
image: postgres:16
container_name: outline-postgres
restart: unless-stopped
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- ./postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 10
redis:
image: redis:7-alpine
container_name: outline-redis
restart: unless-stopped
command: redis-server --appendonly yes
volumes:
- ./redis:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 10
启动并查看日志：
docker compose up -d
docker compose ps
docker compose logs --tail=100 outline
首次启动会执行数据库迁移。如果 outline 反复退出，先看 docker compose logs outline，重点检查 URL、密钥、数据库密码和 OAuth 回调地址，不要直接删除 PostgreSQL 数据目录。
Outline 需要正确的 HTTPS 和 Host 头，否则登录回调、附件 URL 和 Cookie 容易出错。安装 Caddy 后，在 Caddyfile 中写入：
docs.example.com {
reverse_proxy 127.0.0.1:3000
}
Caddy 会自动申请证书。修改后检查：
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://docs.example.com
如果还没有反向代理入口，可参考 VPS 用 Caddy 配置自动 HTTPS。不要把 Outline 的 3000 端口直接暴露给公网。
以 OIDC 兼容身份提供商为例，在管理后台创建应用，回调地址填写：
https://docs.example.com/auth/oidc.callback
将客户端 ID、Secret 和四个 OIDC URL 写入 .env 后重启：
docker compose up -d --force-recreate outline
docker compose logs -f outline
如果登录后跳回首页或出现 redirect_uri mismatch，逐项核对：
- 提供商登记的回调地址是否完全使用 HTTPS；
URL是否与浏览器访问域名一致；- Caddy 是否转发了原始 Host 和协议；
- OIDC 的 issuer、userinfo 和 logout 地址是否属于同一个租户。
修改 OAuth 参数前先保留一条可用的管理员登录路径，避免把所有管理员锁在站外。
测试阶段可以使用 ./data:/var/lib/outline/data，但单机磁盘损坏会同时丢失数据库和附件。生产环境更建议使用 S3 兼容存储，例如此前部署的 VPS MinIO 对象存储，将附件与数据库分开保存。
无论使用本地目录还是 S3，都要限制权限：
chmod 600 /opt/outline/.env
sudo chown -R 1001:1001 /opt/outline/data
不要把附件 bucket 设置为公开写入。前端下载链接应由应用生成，Secret Key 只放在服务端环境变量。
数据库是最重要的备份对象。每天导出 PostgreSQL，同时保存 .env、Compose 文件和附件：
mkdir -p /opt/outline/backups
docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" | gzip > /opt/outline/backups/outline-$(date +%F).sql.gz
tar -czf /opt/outline/backups/outline-config-$(date +%F).tar.gz .env compose.yml
备份不要只留在同一台 VPS。可以结合 VPS 备份恢复演练指南 把压缩包同步到异地，并定期在临时实例恢复一次。
升级前先固定当前镜像版本并备份：
docker compose pull
docker compose up -d
docker compose logs --tail=200 outline
如果新版本迁移失败，不要反复执行破坏性命令；保留日志，回滚到上一个镜像标签，并从数据库备份恢复到隔离实例验证。
确认 Outline 容器是否监听 3000，Caddy 是否代理到 127.0.0.1:3000，并检查：
docker compose ps
curl -I http://127.0.0.1:3000
优先检查 URL、HTTPS、Cookie 域名和系统时间。代理层把 HTTPS 降成 HTTP 时，安全 Cookie 会被浏览器丢弃。
先看 PostgreSQL 日志、磁盘 I/O 和容器内存，再检查 Redis 是否 healthy。不要在没有数据和指标的情况下盲目增加 Node.js 内存。
.env不提交 Git，密钥使用密码管理器保存。- PostgreSQL、Redis、3000 只监听本机或 Docker 内网。
- OAuth 回调只允许正式域名，关闭不需要的自助注册。
- 每周更新系统安全补丁，每次 Outline 升级前做数据库备份。
- 至少保留一份异地数据库和附件副本，并做恢复演练。
- 管理后台可再放到 WireGuard、Tailscale 或 Headscale 私网中。
Outline 的稳定运行取决于四件事：PostgreSQL 持久化、Redis 可用、HTTPS 回调正确、备份能真正恢复。个人测试可以同机运行三个容器；团队生产至少要把数据库和附件纳入异地备份，并在升级前验证迁移和回滚路径。