opencloudeu/opencloud-rolling Docker镜像文档

镜像概述和主要用途

opencloudeu/opencloud-rolling 是 OpenCloud 后端服务的 Docker 镜像，基于 Golang 开发，提供滚动更新（rolling）版本。该镜像封装了 OpenCloud 后端核心服务，用于快速部署具备认证管理、数据存储等功能的后端服务实例。主要用途包括简化 OpenCloud 服务的容器化部署、支持开发/测试环境的快速迭代，以及提供生产环境的后端服务基础。

核心功能和特性

认证与身份管理

• 基于 OpenID Connect 协议实现用户认证
• 支持外部身份提供商（IdP）集成，如 Keycloak
• 内置 LibreGraph Connect 嵌入式身份提供商，简化独立部署场景

数据存储

• 无数据库依赖，所有数据通过文件系统存储
• 默认数据存储路径为服务配置目录，便于持久化和备份

轻量与灵活

• 基于 Golang 构建，镜像体积小，资源占用低
• 滚动更新版本：包含最新开发特性，支持快速迭代测试

使用场景和适用范围

开发环境

• 快速搭建本地测试实例，验证新功能和代码变更
• 简化开发环境配置，避免本地依赖冲突

测试环境

• 部署滚动更新版本，验证最新特性稳定性
• 模拟生产环境架构，进行集成测试和性能测试

企业内部部署

• 作为后端服务组件，提供认证和数据管理功能
• 适用于对轻量级、无数据库依赖有需求的内部系统

详细使用方法和配置说明

前提条件

• 已安装 Docker Engine（20.10+）或 Docker Compose（v2+）
• 持久化存储目录（用于配置和数据持久化）

快速启动（docker run）

1. 初始化配置并启动服务

# 创建本地配置目录（示例路径）
mkdir -p ~/.opencloud/data

# 启动容器（初始化配置并启动服务）
docker run -d \
  --name opencloud-server \
  -p 8080:8080 \  # 映射服务端口（默认假设8080，实际端口以镜像为准）
  -v ~/.opencloud/data:/root/.opencloud \  # 挂载配置和数据目录
  opencloudeu/opencloud-rolling \
  sh -c "opencloud init && opencloud server"

2. 访问服务

服务启动后，可通过 http://localhost:8080 访问（端口需与映射一致）。

Docker Compose 部署

创建 docker-compose.yml 文件：

version: '3.8'

services:
  opencloud:
    image: opencloudeu/opencloud-rolling
    container_name: opencloud-server
    ports:
      - "8080:8080"
    volumes:
      - ./opencloud-data:/root/.opencloud  # 本地目录挂载（当前目录下opencloud-data）
    command: sh -c "opencloud init && opencloud server"
    restart: unless-stopped  # 服务异常时自动重启

启动服务：

docker-compose up -d

初始化配置说明

• opencloud init 命令会在配置目录（默认 /root/.opencloud）生成初始配置文件
• 初始化过程可能需要交互输入基础配置（如管理员账户、服务端口等），可通过环境变量预设（见下文）

配置参数说明

环境变量

挂载点

技术细节

认证机制

• 基于 OpenID Connect 1.0 协议实现用户认证流程
• 支持两种模式：
  • 外部模式：对接第三方 IdP（如 Keycloak），通过 OIDC_PROVIDER 等环境变量配置
  • 内置模式：使用嵌入式 LibreGraph Connect IdP，无需额外部署认证服务

数据存储

• 无数据库依赖，所有数据（用户信息、配置、状态等）以文件形式存储在配置目录下
• 数据文件格式为 JSON 或二进制，确保跨平台兼容性和易备份性

安全注意事项

• 持久化目录权限：宿主机挂载目录需限制权限（如 chmod 700），避免敏感配置文件泄露
• 安全漏洞报告：发现安全相关问题，请立即联系 ***
• 外部 IdP 配置：使用外部身份提供商时，确保传输通道（HTTPS）和密钥管理安全

参与贡献

该镜像基于 OpenCloud 项目构建，欢迎通过以下方式参与贡献：

• 报告问题或缺陷：GitHub Issues
• 提交功能需求：GitHub Issues
• 贡献代码或文档：GitHub Pull Requests
• 社区支持：Matrix 房间

许可证

本镜像基于 Apache 2.0 许可证 开源，详情参见项目 LICENSE 文件。