HL6 Docker Compose 部署教程

发表于
更新于
开发日志
14 1.7~2.2 分钟 754

项目：HouLangCloud / Hl6 · GitLab

本文章仅做技术分享。部署本项目前请确保有运营本项目内容所需的所有资质。

本文由 AI 根据给定项目和 Docker Compose 配置文件生成。

一、前置要求

在开始部署前，请确保已安装：

  • Docker（版本 20.10+）

  • Docker Compose（V2 版本，即 docker compose 命令）

二、部署步骤

1. 准备配置文件

创建 docker-compose.yml 文件，内容如下：

version: "3.9"
​
services:
  main:
    image: registry.houlang.cloud/houlangcloud/hl6/app:v3.3.0
    restart: unless-stopped
    depends_on:
      - postgres
    environment:
      SERVER_PORT: "8080"
      APP_URL: https://hl6.example.com
      FRONTEND_URL: ${APP_URL}
      BACKEND_URL: ${APP_URL}
      ALLOWED_ORIGINS: ${APP_URL}
      POSTGRES_DB: hl6
      POSTGRES_USER: hl6
      POSTGRES_PASSWORD: change-me-db-password
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable
      OIDC_ISSUER: https://your-oidc-provider.example.com
      OIDC_CLIENT_ID: your-client-id
      OIDC_CLIENT_SECRET: your-client-secret
      SESSION_SECRET: ""
      ENCRYPTION_KEY: ""
    ports:
      - "8080:8080"
​
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: hl6
      POSTGRES_USER: hl6
      POSTGRES_PASSWORD: change-me-db-password
    expose:
      - "5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
​
volumes:
  postgres-data:

2. 配置必要的环境变量

在部署前，必须修改以下关键配置：

2.1 域名配置

APP_URL: https://hl6.example.com  # 改为你的实际域名

2.2 数据库配置

POSTGRES_PASSWORD: change-me-db-password  # 改为强密码

2.3 OIDC 认证配置

OIDC_ISSUER: https://your-oidc-provider.example.com  # 改为你的 OIDC 提供商地址
OIDC_CLIENT_ID: your-client-id                       # 改为你的客户端 ID
OIDC_CLIENT_SECRET: your-client-secret               # 改为你的客户端密钥

2.4 安全配置（可选但推荐）

SESSION_SECRET: ""  # 留空会自动生成，建议首次启动后从数据库获取并填入
ENCRYPTION_KEY: ""  # 如需加密 Cloudflare Token，填写 64 位十六进制密钥

3. 启动服务

# 启动所有服务
docker compose up -d
​
# 查看服务状态
docker compose ps
​
# 查看日志
docker compose logs -f

4. 验证部署

启动成功后，访问以下地址验证：

  • 前端页面：https://hl6.example.com（替换为你的域名）

  • 后端 API：https://hl6.example.com/api/v1

三、常用运维命令

# 停止服务
docker compose down
​
# 停止并删除数据卷（谨慎使用）
docker compose down -v
​
# 重启服务
docker compose restart
​
# 更新镜像
docker compose pull
docker compose up -d

四、注意事项

  1. 端口冲突：确保 8080 端口未被占用

  2. 数据持久化：PostgreSQL 数据存储在 postgres-data 卷中，删除容器不会丢失数据

  3. 反向代理：生产环境建议使用 Nginx/Caddy 配置 HTTPS

  4. 首次启动：SESSION_SECRET 留空会自动生成，建议首次启动后从数据库获取并固定配置

五、故障排查

5.1 数据库连接失败

检查 DATABASE_URL 配置是否正确，确保 postgres 服务名未被修改

5.2 OIDC 认证失败

验证 OIDC_ISSUER、OIDC_CLIENT_ID 和 OIDC_CLIENT_SECRET 配置是否正确

5.3 无法访问前端

检查 APP_URL 和 ALLOWED_ORIGINS 是否配置为实际域名

六、生产环境建议

  1. 使用强密码替换所有默认密码

  2. 配置 HTTPS 证书

  3. 设置定期数据库备份

  4. 配置日志轮转

  5. 启用资源限制（CPU/ 内存）