Meshcentral-Docker 镜像文档

!Docker Pulls !Docker Image Size (latest by date)

镜像概述和主要用途

本镜像为 MeshCentral 软件（***项目）的 Docker 化实现，通过优化初始设置流程简化部署过程。MeshCentral 是一款功能强大的远程设备管理平台，支持远程桌面、文件传输、设备监控等功能。

注意：尽管本镜像简化了部署流程，仍建议参考***文档以获取完整配置指南：

• MeshCentral 安装指南
• MeshCentral 用户指南

核心功能和特性

• 简化初始配置：通过环境变量快速定义基础设置，无需手动编辑配置文件即可启动
• 持久化存储：支持数据、配置文件和用户文件的持久化存储，确保容器重启后数据不丢失
• 自动备份：内置自动备份功能，可配置备份密码、间隔和保留天数
• MongoDB 支持：提供专用镜像版本，支持 MongoDB 数据库以适应更大规模部署
• 灵活配置扩展：支持通过自定义 config.json 文件实现高级配置（需参考***用户指南）
• 多架构支持：通过 GitHub Actions 构建多架构镜像，适配不同硬件平台
• 环境变量动态调整：部分核心设置可通过环境变量定义，便于自动化部署

使用场景和适用范围

• 适用场景：个人或小型团队的自托管远程设备管理、中小企业内部设备监控与维护
• 规模限制：
  • 常规镜像（未集成 MongoDB）：根据***文档建议，适用于设备数量不超过 100 台的环境
  • MongoDB 版本镜像：通过外部数据库支持，可适应更大规模部署

详细使用方法和配置说明

部署方式

推荐使用 docker-compose 进行部署，以下提供常规部署和 MongoDB 集成部署两种示例。

常规部署（无 MongoDB）

version: '3'
services:
    meshcentral:
        restart: always
        container_name: meshcentral
        image: typhonragewind/meshcentral:latest
        ports:
            - 8086:443  # 默认使用443端口，若需使用80端口需修改后续生成的config.json
        environment:
            - HOSTNAME=my.domain.com     # 服务器主机名（必填）
            - REVERSE_PROXY=false     # 反向代理IP（如使用反向代理，填写代理服务器IP；否则为false）
            - REVERSE_PROXY_TLS_PORT=     # 反向代理TLS端口（仅在启用反向代理时设置）
            - IFRAME=false    # 是否启用iframe嵌入支持（true/false）
            - ALLOW_NEW_ACCOUNTS=true    # 是否允许用户自助创建账户（首个管理员账户除外）
            - WEBRTC=false  # 是否启用WebRTC（***未正式发布，可能存在不稳定，建议谨慎启用）
            - BACKUPS_PW=MyAwesomePasswordPleaseChangeMe # 自动备份加密密码（建议修改为强密码）
            - BACKUP_INTERVAL=24 # 自动备份间隔（单位：小时，默认24）
            - BACKUP_KEEP_DAYS=10 # 备份文件保留天数（默认10）
        volumes:
            - ./meshcentral/data:/opt/meshcentral/meshcentral-data    # 配置文件及核心数据存储目录
            - ./meshcentral/user_files:/opt/meshcentral/meshcentral-files    # 用户上传文件存储目录
            - ./meshcentral/backups:/opt/meshcentral/meshcentral-backups     # 自动备份文件存储目录

MongoDB 集成部署

适用于需要支持超过 100 台设备的场景：

version: '3'
services:
    mongodb:
        container_name: meshcentral_db
        restart: always
        image: mongo:latest
        expose:
            - 27017  # MongoDB 默认端口
        volumes:
            - '/opt/meshcentral/database:/data/db'  # MongoDB 数据持久化目录
    meshcentral:
        restart: always
        container_name: meshcentral
        depends_on:
            - 'mongodb'  # 确保MongoDB服务先启动
        image: typhonragewind/meshcentral:mongodb-latest
        ports:
            - 8086:443 # 默认使用443端口
        environment:
            - HOSTNAME=my.domain.com     # 服务器主机名（必填）
            - REVERSE_PROXY=false     # 反向代理IP（如使用反向代理，填写代理服务器IP；否则为false）
            - REVERSE_PROXY_TLS_PORT=443     # 反向代理TLS端口（仅在启用反向代理时设置）
            - IFRAME=false # 是否启用iframe嵌入支持（true/false）
            - ALLOW_NEW_ACCOUNTS=true    # 是否允许用户自助创建账户
            - WEBRTC=false  # 是否启用WebRTC（同上，谨慎启用）
            - NODE_ENV=production  # 运行环境（固定为production）
        volumes:
            - ./meshcentral/data:/opt/meshcentral/meshcentral-data    # 配置文件及核心数据目录
            - ./meshcentral/user_files:/opt/meshcentral/meshcentral-files    # 用户文件存储目录

环境变量详细说明

卷挂载说明

配置文件自定义

1. 初始配置：若需定义环境变量未覆盖的高级设置，可在首次启动容器前，将自定义 config.json 文件放入 ./meshcentral/data 目录（需参考***用户指南配置格式）。

2. 配置更新：容器运行中如需修改配置，可直接编辑 ./meshcentral/data/config.json 文件，保存后重启容器使配置生效：

   docker restart meshcentral
   

镜像标签说明

本镜像提供多种标签，适用于不同场景：

常规镜像（无 MongoDB）

• typhonragewind/meshcentral:latest：最新稳定版
• typhonragewind/meshcentral:preloadlibs-latest：预加载依赖库的最新版（解决部分环境依赖安装问题）
• typhonragewind/meshcentral:<版本号>：指定版本（如 typhonragewind/meshcentral:1.1.12）
• typhonragewind/meshcentral:preloadlibs-<版本号>：预加载依赖库的指定版本

MongoDB 集成镜像

• typhonragewind/meshcentral:mongodb-latest：MongoDB 支持的最新稳定版
• typhonragewind/meshcentral:preloadlibs-mongodb-latest：预加载依赖库的 MongoDB 最新版
• typhonragewind/meshcentral:mongodb-<版本号>：MongoDB 支持的指定版本
• typhonragewind/meshcentral:preloadlibs-mongodb-<版本号>：预加载依赖库的 MongoDB 指定版本

说明：所有标签均在 Docker Hub 和 ghcr.io 同时提供。

常见问题与故障排除

无法通过环境变量修改已初始化的设置？

当前版本中，首次启动容器时环境变量会写入 config.json，后续修改环境变量不会自动更新配置。解决方法：

• 直接编辑 meshcentral-data/config.json 文件后重启容器
• 删除 meshcentral-data/config.json 文件，重新启动容器使新环境变量生效（会重置配置，谨慎操作）

提示 "Unable to install required module 'otplib@10.2.3'"？

该问题偶发于部分环境，原因未明。解决方案：使用带有 preloadlibs 前缀的镜像标签（如 preloadlibs-latest），此类镜像预加载了依赖库。

更新日志

• 2023-06-22：实现多架构镜像构建；通过 GitHub Actions 自动构建并同步至 Docker Hub 和 GitHub Registry；新增预加载依赖库的镜像标签；为常规镜像添加自动备份功能及配置选项。
• 2022-06-22：指定 Ubuntu 基础镜像版本以修复构建问题；优化文档内容。
• 2022-05-20：添加 Docker Hub 镜像版本标签，支持未来自动化构建。