Outline 自托管部署指南 | 向野而深的博客

1. 概览
2. 架构与数据流
3. 先决条件
4. 部署步骤
5. 验证与排查
6. 进阶优化
7. 官方文档系列
8. 教程与参考部署

1. 概览

目标：自托管 Outline，构建团队知识库与协作文档系统。
组成：Outline 应用、Nginx 反向代理、Keycloak OIDC 登录、PostgreSQL、Redis、MinIO 对象存储。
结果：提供可靠的文档撰写、组织与权限体系，支持 S3 兼容存储与主流身份认证。

alt text

2. 架构与数据流

浏览器访问 Nginx → 反向代理到 Outline 服务。
Outline 读写 PostgreSQL、Redis，并将附件与导出内容存储到 MinIO。
如启用 Keycloak，用户通过 OIDC 完成单点登录。

3. 先决条件

已安装 Docker 与 Docker Compose。
可用域名与 SSL 证书（或使用反向代理自动签发）。
服务器开放端口：80、443，以及内部服务端口。

4. 部署步骤

4.1 Docker Compose 栈

将以下内容保存为 docker-compose.yml，并按需替换域名与密钥：

version: "3.8"
services:
  postgres:
    image: postgres:12
    environment:
      POSTGRES_USER: outline
      POSTGRES_PASSWORD: outline
      POSTGRES_DB: outline
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

  redis:
    image: redis:6
    command: redis-server --appendonly yes
    volumes:
      - ./data/redis:/data

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - ./data/minio:/data
    ports:
      - "9000:9000"
      - "9001:9001"

  outline:
    image: outlinewiki/outline:latest
    depends_on:
      - postgres
      - redis
      - minio
    environment:
      URL: https://wiki.example.com
      SECRET_KEY: changeme_secret
      UTILS_SECRET: changeme_utils_secret
      DATABASE_URL: postgres://outline:outline@postgres:5432/outline
      REDIS_URL: redis://redis:6379
      AWS_ACCESS_KEY_ID: minioadmin
      AWS_SECRET_ACCESS_KEY: minioadmin
      AWS_S3_UPLOAD_BUCKET_NAME: outline
      AWS_S3_UPLOAD_BUCKET_URL: http://minio:9000/outline
      AWS_S3_FORCE_PATH_STYLE: "true"
    ports:
      - "3000:3000"

4.2 环境变量示例

将敏感信息放入 .env 文件并由 Compose 读取：

URL=https://wiki.example.com
SECRET_KEY=changeme_secret
UTILS_SECRET=changeme_utils_secret
DATABASE_URL=postgres://outline:outline@postgres:5432/outline
REDIS_URL=redis://redis:6379
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_S3_UPLOAD_BUCKET_NAME=outline
AWS_S3_UPLOAD_BUCKET_URL=http://minio:9000/outline
AWS_S3_FORCE_PATH_STYLE=true

4.3 初始化 MinIO

创建对象桶用于附件与导出：

mc alias set minio http://localhost:9000 minioadmin minioadmin
mc mb minio/outline

4.4 Nginx 反向代理与 SSL

示例虚拟主机配置：

server {
  listen 443 ssl;
  server_name wiki.example.com;
  ssl_certificate /etc/nginx/ssl/fullchain.pem;
  ssl_certificate_key /etc/nginx/ssl/privkey.pem;
  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}
server {
  listen 80;
  server_name wiki.example.com;
  return 301 https://$host$request_uri;
}

4.5 接入 Keycloak（OIDC）

在 Keycloak 创建客户端，设置回调地址： https://wiki.example.com/auth/oidc.callback
在 Outline 环境变量中启用 OIDC：

OIDC_CLIENT_ID=outline
OIDC_CLIENT_SECRET=changeme_oidc_secret
OIDC_DISCOVERY_URI=https://keycloak.example.com/realms/example/.well-known/openid-configuration
OIDC_SCOPES=openid profile email

4.6 启动与验证

启动服务：
```
docker compose up -d
```
查看日志：
```
docker compose logs -f outline
```
访问站点：https://wiki.example.com

5. 验证与排查

应用无法访问：检查 Nginx 反代与端口映射是否正确，确认 URL 指向 HTTPS。
对象存储失败：确认 MinIO 桶已创建，AWS_S3_FORCE_PATH_STYLE 为 true，访问密钥正确。
数据库连接错误：DATABASE_URL 用户、密码与 DB 名保持一致。
登录回调失败：Keycloak 客户端的重定向 URL 与 Outline 的回调路径一致。
静态资源 404：确认 URL 与代理头部 Host、X-Forwarded-Proto 设置正确。

6. 进阶优化

备份策略：定期备份 PostgreSQL 数据与 MinIO 对象。
安全加固：将所有密钥置于环境变量或密钥管理服务，避免写入镜像。
可用性：为 Outline、PostgreSQL、Redis 添加健康检查与重启策略。
扩展：接入 CDN 加速附件访问，或使用外部 S3 服务。

7. 官方文档系列

Outline：https://docs.getoutline.com/s/hosting/doc/docker-7pfeLP5a8t
Nginx：https://nginx.org/en/docs/
Keycloak：https://www.keycloak.org/documentation.html
Keycloak（中文）：https://keycloak.org.cn/docs/latest/getting_started/index.html
MinIO for Docker：https://min.io/docs/minio/container/index.html
PostgreSQL 12：https://www.postgresql.org/docs/12/index.html
Redis：https://redis.io/docs/

8. 教程与参考部署

Outline 搭建：https://biteax.com/b9dce220.html
Outline 搭建：https://github.com/soulteary/docker-outline
Outline 搭建：https://zhuanlan.zhihu.com/p/411062890
Keycloak 搭建：https://gitee.com/itmuch/spring-cloud-yes/tree/master/doc/keycloak-learn
Keycloak+Outline 搭建：https://blog.yarsalabs.com/self-hosting-outline-wiki-on-cloudron/
Docker 部署 Outline 指南：https://biteax.com/b9dce220.html
Outline 服务器搭建部署：https://jiang-taibai.github.io/deploy-outline-via-nginx/