Windows 本地 Docker 部署 DataCap 实战：从启动失败到插件离线安装完整记录

本文记录一次在 Windows 11 本地环境中使用 Docker Compose 部署 DataCap 的完整过程。过程中踩到了 Docker Desktop 未启动、镜像名称错误、MySQL 初始化脚本缺失、插件元数据 CDN 不可访问、插件版本不匹配、插件安装 URL 被破坏、SQL Server 元数据查询兼容性等问题。本文会逐一说明排查过程和最终解决方案。
本文由AI总结生成

一、部署目标

本次目标是在本地电脑上部署一套可用的 DataCap 环境，最终实现：

DataCap Web 页面可访问
MySQL 作为 DataCap 元数据库
Redis 作为缓存服务
插件商店元数据本地化
常用插件离线安装到 DataCap
能够连接常见数据源，例如 MySQL、SQL Server、PostgreSQL、ClickHouse 等

最终访问地址：

http://localhost:9096

默认登录账号一般为：

用户名：admin
密码：12345678

注意：默认密码仅适合本地测试环境。生产或长期使用环境请务必修改默认密码，并调整数据库密码、端口暴露和网络访问策略。

二、环境准备

本次部署环境如下：

组件	版本 / 状态
操作系统	Windows 11
Docker	Docker Desktop 29.5.2
Java	OpenJDK 21，本次 Docker 部署不直接依赖宿主机 Java
Git	已安装
DataCap 镜像	`devliveorg/datacap:latest`，实际应用版本为 `2025.1.1`
MySQL	`mysql:8.0`
Redis	`redis:7-alpine`
Nginx	`nginx:alpine`，用于本地托管插件元数据

部署前建议先检查：

docker --version
docker info

如果出现类似下面错误：

failed to connect to the docker API at npipe:////./pipe/dockerDesktopLinuxEngine

说明 Docker Desktop 客户端已安装，但 Docker 引擎没有启动。先启动 Docker Desktop，等待 Docker Engine 初始化完成后再继续。

三、几个关键结论先说明

1. DataCap 官方 Docker 镜像名称

一开始容易误用：

edurtio/datacap:latest

实际可用镜像为：

devliveorg/datacap:latest

拉取命令：

docker pull devliveorg/datacap:latest

2. DataCap 需要 MySQL 初始化脚本

DataCap 容器启动时不会自动完整创建所有业务表。官方 Docker Compose 方式依赖：

configure/schema/datacap.sql

需要将该 SQL 挂载到 MySQL 容器的初始化目录：

/docker-entrypoint-initdb.d/schema.sql

否则 DataCap 启动时可能出现类似：

Table 'datacap.datacap_scheduled' doesn't exist

3. 插件商店默认元数据地址可能不可访问

DataCap 前端插件商店默认地址为：

https://cdn.north.devlive.org/applications/datacap/metadata/metadata.json

实际部署时该域名可能 DNS 解析失败。因此本文采用本地 Nginx 托管 metadata.json 的方式解决。

4. 插件版本需要和 DataCap 版本一致

如果使用 GitHub dev 分支的 metadata.json，其中插件版本可能是：

2026.0.0

但本次 DataCap 镜像实际版本是：

2025.1.1

Maven Central 上可下载的插件版本也是 2025.1.1。版本不匹配会导致插件下载 404。

四、目录结构

建议本地准备如下目录：

datacap/
├── docker-compose.yml
├── datacap.sql
├── docker-application.properties
├── metadata.json
├── nginx-metadata.conf
├── plugins/
│   ├── datacap-plugin-mysql.tar.gz
│   ├── datacap-plugin-sqlserver.tar.gz
│   └── ...
├── download-plugins.ps1
└── install-plugins.sh

其中：

文件	作用
`docker-compose.yml`	编排 DataCap、MySQL、Redis、Nginx
`datacap.sql`	DataCap 元数据库初始化脚本
`docker-application.properties`	DataCap Docker 运行配置
`metadata.json`	插件商店元数据
`nginx-metadata.conf`	本地元数据服务 Nginx 配置
`plugins/`	离线插件包目录

五、下载官方配置文件

官方文件来源：

https://github.com/devlive-community/datacap

需要下载：

configure/schema/datacap.sql
configure/docker/application.properties
configure/metadata.json

如果可以直接访问 raw.githubusercontent.com，可以使用：

curl -L -o datacap.sql https://raw.githubusercontent.com/devlive-community/datacap/dev/configure/schema/datacap.sql
curl -L -o docker-application.properties https://raw.githubusercontent.com/devlive-community/datacap/dev/configure/docker/application.properties
curl -L -o metadata.json https://raw.githubusercontent.com/devlive-community/datacap/dev/configure/metadata.json

如果 raw 地址访问不稳定，也可以通过 GitHub API 下载并 base64 解码。

PowerShell 示例：

$headers = @{ 'User-Agent' = 'datacap-deploy' }

$r = Invoke-RestMethod `
  -Uri 'https://api.github.com/repos/devlive-community/datacap/contents/configure/schema/datacap.sql?ref=dev' `
  -Headers $headers
[System.IO.File]::WriteAllBytes('datacap.sql', [System.Convert]::FromBase64String($r.content))

$r = Invoke-RestMethod `
  -Uri 'https://api.github.com/repos/devlive-community/datacap/contents/configure/docker/application.properties?ref=dev' `
  -Headers $headers
[System.IO.File]::WriteAllBytes('docker-application.properties', [System.Convert]::FromBase64String($r.content))

$r = Invoke-RestMethod `
  -Uri 'https://api.github.com/repos/devlive-community/datacap/contents/configure/metadata.json?ref=dev' `
  -Headers $headers
[System.IO.File]::WriteAllBytes('metadata.json', [System.Convert]::FromBase64String($r.content))

六、调整 DataCap 配置

官方 Docker 配置中的 MySQL 地址通常为：

spring.datasource.url=jdbc:mysql://app-mysql:3306/datacap?useUnicode=true&characterEncoding=UTF-8&zeroDateTimeBehavior=convertToNull&allowMultiQueries=true&useSSL=false&useOldAliasMetadataBehavior=true&jdbcCompliantTruncation=false&allowPublicKeyRetrieval=true
spring.datasource.username=root
spring.datasource.password=12345678

如果增加 Redis 容器，建议将 Redis 地址改成 Compose 服务名：

spring.redis.host=app-redis
spring.redis.port=6379
spring.redis.database=0

同时确认服务监听地址：

server.address=0.0.0.0
server.port=9096

七、插件元数据本地化

由于默认 CDN 地址可能不可访问，增加一个 Nginx 容器用于托管 metadata.json。

nginx-metadata.conf 内容如下：

server {
    listen 80;
    server_name localhost;

    location / {
        add_header Access-Control-Allow-Origin * always;
        add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
        add_header Access-Control-Allow-Headers "*" always;

        if ($request_method = OPTIONS) {
            return 204;
        }

        root /usr/share/nginx/html;
        index metadata.json;
    }
}

启动后插件元数据地址为：

http://localhost:9097/metadata.json

DataCap 插件商店页面会先从浏览器 localStorage 中读取 metadataUrl。因此可以在浏览器控制台执行：

localStorage.setItem('metadataUrl', 'http://localhost:9097/metadata.json')

也可以在插件商店右上角齿轮按钮中手动设置元数据地址。

八、Docker Compose 文件

完整 docker-compose.yml 示例：

services:
  # MySQL 元数据库，首次启动会自动导入 datacap.sql
  app-mysql:
    image: mysql:8.0
    container_name: datacap-mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: "12345678"
      MYSQL_DATABASE: datacap
      TZ: Asia/Shanghai
    command: >
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci
      --default-authentication-plugin=mysql_native_password
    ports:
      - "3307:3306"
    volumes:
      - ./datacap.sql:/docker-entrypoint-initdb.d/schema.sql
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p12345678"]
      interval: 10s
      timeout: 5s
      retries: 10
    networks:
      - datacap-net

  # Redis 缓存
  app-redis:
    image: redis:7-alpine
    container_name: datacap-redis
    restart: unless-stopped
    ports:
      - "6380:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - datacap-net

  # DataCap 应用
  app-datacap:
    image: devliveorg/datacap:latest
    container_name: datacap
    restart: unless-stopped
    ports:
      - "9096:9096"
    volumes:
      - ./docker-application.properties:/opt/app/datacap/configure/application.properties
      - datacap_data:/opt/app/datacap/data
    depends_on:
      app-mysql:
        condition: service_healthy
      app-redis:
        condition: service_healthy
    networks:
      - datacap-net

  # 插件商店元数据服务
  app-metadata:
    image: nginx:alpine
    container_name: datacap-metadata
    restart: unless-stopped
    ports:
      - "9097:80"
    volumes:
      - ./metadata.json:/usr/share/nginx/html/metadata.json
      - ./nginx-metadata.conf:/etc/nginx/conf.d/default.conf
    networks:
      - datacap-net

volumes:
  mysql_data:
  redis_data:
  datacap_data:

networks:
  datacap-net:
    driver: bridge

安全提醒：示例中的 MySQL root 密码为官方默认值，仅适用于本地测试。正式使用请修改密码，并同步调整 docker-application.properties。

九、启动服务

在 docker-compose.yml 所在目录执行：

docker compose up -d

查看容器状态：

docker ps

预期看到：

datacap            Up    0.0.0.0:9096->9096/tcp
datacap-mysql      Up    0.0.0.0:3307->3306/tcp
datacap-redis      Up    0.0.0.0:6380->6379/tcp
datacap-metadata   Up    0.0.0.0:9097->80/tcp

验证 Web 服务：

curl http://localhost:9096

或者浏览器访问：

http://localhost:9096

验证元数据服务：

curl http://localhost:9097/metadata.json

十、插件安装问题与离线安装方案

1. 问题现象

在插件商店点击安装时，可能看到类似日志：

Unsupported plugin type for: https:/repo1.maven.org/maven2/io/edurt/datacap/...
Failed to download file from URL: https://repo1.maven.org/maven2/io/edurt/datacap/...

这里有两个问题：

URL 在日志中从 https:// 变成了 https:/
metadata 中的插件版本可能是 2026.0.0，但 Maven Central 中实际可用版本是 2025.1.1

2. 修正 metadata.json 插件版本

如果 metadata.json 中存在 2026.0.0，可以替换为当前 DataCap 版本 2025.1.1：

PowerShell：

(Get-Content '.\metadata.json' -Raw) `
  -replace '2026\.0\.0','2025.1.1' |
  Set-Content '.\metadata.json' -NoNewline

3. 下载 2025.1.1 插件包

插件包 Maven 地址格式如下：

https://repo1.maven.org/maven2/io/edurt/datacap/{插件名}/2025.1.1/{插件名}-2025.1.1-bin.tar.gz

例如 MySQL 插件：

https://repo1.maven.org/maven2/io/edurt/datacap/datacap-plugin-mysql/2025.1.1/datacap-plugin-mysql-2025.1.1-bin.tar.gz

可以先从容器中查看官方插件列表：

docker exec datacap cat /opt/app/datacap/configure/plugin.conf

然后按插件名批量下载。

PowerShell 简化示例：

$VERSION = "2025.1.1"
$BASE_URL = "https://repo1.maven.org/maven2/io/edurt/datacap"
$PLUGINS_DIR = ".\plugins"

New-Item -ItemType Directory -Force -Path $PLUGINS_DIR | Out-Null

$plugins = @(
  "datacap-plugin-mysql",
  "datacap-plugin-sqlserver",
  "datacap-plugin-postgresql",
  "datacap-plugin-clickhouse",
  "datacap-plugin-redis",
  "datacap-convert-json",
  "datacap-convert-csv"
)

foreach ($plugin in $plugins) {
  $url = "$BASE_URL/$plugin/$VERSION/$plugin-$VERSION-bin.tar.gz"
  $outFile = "$PLUGINS_DIR\$plugin.tar.gz"
  Write-Host "Downloading $plugin ..."
  Invoke-WebRequest -Uri $url -OutFile $outFile -UseBasicParsing
}

如果希望完整安装所有插件，可以将 plugin.conf 中的插件名全部加入数组。

4. 解压插件到 DataCap 插件目录

本次实践中，最终将插件解压到容器内：

/opt/app/datacap/plugins

可以通过临时容器或 docker cp 方式安装。

示例方式一：先拷贝插件包到容器，再进入容器解压：

docker cp ./plugins/. datacap:/tmp/plugins/

docker exec datacap sh -c "\
  mkdir -p /opt/app/datacap/plugins && \
  cd /opt/app/datacap/plugins && \
  for f in /tmp/plugins/*.tar.gz; do tar -xzf \"$f\"; done"

示例方式二：使用临时 Alpine 容器解压到 DataCap 数据卷，再拷贝到插件目录：

docker run -d --name plugin-installer \
  -v "$PWD/plugins:/plugins" \
  -v datacap_datacap_data:/data \
  alpine sh -c "\
    mkdir -p /data/plugins && \
    cd /data/plugins && \
    for f in /plugins/*.tar.gz; do tar -xzf \"$f\"; done && \
    echo ALL_DONE > /data/plugins/install_complete.flag"

然后：

docker exec datacap sh -c "\
  mkdir -p /opt/app/datacap/plugins && \
  cp -r /opt/app/datacap/data/plugins/* /opt/app/datacap/plugins/"

最后重启 DataCap：

docker restart datacap

查看插件加载日志：

docker logs datacap | grep "Install plugin"

在 Windows CMD 中可以使用：

docker logs datacap 2>&1 | findstr "Install plugin"

本次实践中，最终约 68 个插件成功加载。

十一、常见问题排查

问题 1：Docker Desktop 未启动

错误：

failed to connect to the docker API at npipe:////./pipe/dockerDesktopLinuxEngine

解决：

启动 Docker Desktop，等待 Docker Engine 完全启动后再执行：

docker info

问题 2：镜像拉取失败或镜像名错误

错误镜像名：

edurtio/datacap:latest

正确镜像名：

devliveorg/datacap:latest

问题 3：DataCap 启动时报 MySQL 连接失败

错误：

Communications link failure
Connection refused

常见原因：

MySQL 容器未启动完成
DataCap 配置仍然连接 localhost:3306
Compose 服务名写错

容器内应使用服务名：

spring.datasource.url=jdbc:mysql://app-mysql:3306/datacap?...

问题 4：缺少数据库表

错误：

Table 'datacap.datacap_scheduled' doesn't exist

解决：

确保 datacap.sql 正确挂载：

volumes:
  - ./datacap.sql:/docker-entrypoint-initdb.d/schema.sql

如果 MySQL 已经初始化过但没有导入 SQL，需要删除旧 volume 后重新启动：

docker compose down -v
docker compose up -d

注意：down -v 会删除数据卷，生产环境不要随意执行。

问题 5：插件商店空白或加载失败

如果默认地址不可访问：

https://cdn.north.devlive.org/applications/datacap/metadata/metadata.json

可以改为本地地址：

http://localhost:9097/metadata.json

浏览器控制台执行：

localStorage.setItem('metadataUrl', 'http://localhost:9097/metadata.json')

问题 6：安装插件时报 `Unsupported plugin type`

可能原因：

插件 URL 被程序处理成了 https:/...
插件版本不存在，例如 metadata 写的是 2026.0.0，但 Maven Central 只有 2025.1.1
容器内下载插件失败

建议方案：

修正 metadata 插件版本为 DataCap 当前版本
离线下载插件包
解压到 /opt/app/datacap/plugins
重启 DataCap

十二、SQL Server 插件兼容性问题

连接 SQL Server 后，展开元数据树时可能报：

java.sql.SQLException: com.microsoft.sqlserver.jdbc.SQLServerException: 'FIELD' is not a recognized built-in function name.

根因是 DataCap 的通用元数据 SQL 使用了 MySQL 方言：

FIELD(type, 'BASE TABLE', 'VIEW', 'FUNCTION', 'PROCEDURE')

FIELD() 是 MySQL 函数，SQL Server 不支持。

影响范围：

功能	影响
手写 SQL 查询 SQL Server	不受影响
SQL 编辑器执行查询	不受影响
元数据树展开表/视图/函数	受影响
查看表结构详情	可能受影响

临时解决方案：

直接在 SQL 编辑器中手写 SQL 查询
避免依赖元数据树展开 SQL Server 对象

根本解决方案：

等待 DataCap 官方修复 SQL Server 元数据查询方言
或自行修改 SqlServerService，重写 getTables()、getColumns() 等元数据方法后重新打包插件

十三、常用运维命令

启动：

docker compose up -d

停止：

docker compose down

查看容器：

docker ps

查看 DataCap 日志：

docker logs datacap --tail 100

查看 MySQL 日志：

docker logs datacap-mysql --tail 100

查看插件加载情况：

docker logs datacap 2>&1 | findstr "Install plugin"

验证 DataCap：

curl http://localhost:9096

验证插件元数据：

curl http://localhost:9097/metadata.json

十四、总结

本次 DataCap 本地部署看似只是一次 Docker Compose 启动，但实际涉及到多个关键点：

DataCap 官方镜像应使用 devliveorg/datacap
MySQL 必须挂载 datacap.sql 完成初始化
DataCap 容器内连接 MySQL 应使用 Compose 服务名，而不是 localhost
插件商店默认 CDN 地址可能不可用，需要本地化 metadata
metadata 中插件版本必须与 DataCap 版本一致
插件在线安装存在 URL 或版本问题时，可以采用离线安装方案
SQL Server 插件的元数据树功能存在 MySQL 方言兼容性问题，但手写 SQL 查询不受影响

最终部署完成后，本地环境包含：

服务	地址
DataCap	`http://localhost:9096`
插件元数据	`http://localhost:9097/metadata.json`
MySQL	`localhost:3307`
Redis	`localhost:6380`

这套部署方式比较适合本地测试、插件验证、数据源连接调试和团队内部 PoC。如果用于生产环境，还需要进一步完善密码管理、网络隔离、数据卷备份、HTTPS、日志留存和监控告警。

posted on 2026-07-01 14:08 微想乐阅读(0) 评论(0) 收藏举报

刷新页面返回顶部

微想乐的园子

公告

Windows 本地 Docker 部署 DataCap 实战：从启动失败到插件离线安装完整记录

一、部署目标

二、环境准备

三、几个关键结论先说明

1. DataCap 官方 Docker 镜像名称

2. DataCap 需要 MySQL 初始化脚本

3. 插件商店默认元数据地址可能不可访问

4. 插件版本需要和 DataCap 版本一致

四、目录结构

五、下载官方配置文件

六、调整 DataCap 配置

七、插件元数据本地化

八、Docker Compose 文件

九、启动服务

十、插件安装问题与离线安装方案

1. 问题现象

2. 修正 metadata.json 插件版本

3. 下载 2025.1.1 插件包

4. 解压插件到 DataCap 插件目录

十一、常见问题排查

问题 1：Docker Desktop 未启动

问题 2：镜像拉取失败或镜像名错误

问题 3：DataCap 启动时报 MySQL 连接失败

问题 4：缺少数据库表

问题 5：插件商店空白或加载失败

问题 6：安装插件时报 `Unsupported plugin type`

十二、SQL Server 插件兼容性问题

十三、常用运维命令

十四、总结

微想乐的园子

公告

Windows 本地 Docker 部署 DataCap 实战：从启动失败到插件离线安装完整记录

一、部署目标

二、环境准备

三、几个关键结论先说明

1. DataCap 官方 Docker 镜像名称

2. DataCap 需要 MySQL 初始化脚本

3. 插件商店默认元数据地址可能不可访问

4. 插件版本需要和 DataCap 版本一致

四、目录结构

五、下载官方配置文件

六、调整 DataCap 配置

七、插件元数据本地化

八、Docker Compose 文件

九、启动服务

十、插件安装问题与离线安装方案

1. 问题现象

2. 修正 metadata.json 插件版本

3. 下载 2025.1.1 插件包

4. 解压插件到 DataCap 插件目录

十一、常见问题排查

问题 1：Docker Desktop 未启动

问题 2：镜像拉取失败或镜像名错误

问题 3：DataCap 启动时报 MySQL 连接失败

问题 4：缺少数据库表

问题 5：插件商店空白或加载失败

问题 6：安装插件时报 Unsupported plugin type

十二、SQL Server 插件兼容性问题

十三、常用运维命令

十四、总结

问题 6：安装插件时报 `Unsupported plugin type`