跳到主要内容
支持地域：上海

微搭私有部署常见问题解答

本文档整理了微搭私有部署过程中的常见问题和解决方案，帮助您快速解决部署和使用中遇到的问题。

安装部署问题​

系统兼容性​

Q1：微搭私有部署版本是否支持 Windows 系统？​

A： 不支持。微搭私有部署仅支持 Linux 系统，请参考 机器配置要求 了解详细的系统要求。

License 相关​

Q2：License 激活码是否可以多次使用？​

A： 不可以。每个 License 激活码只能在一台 CVM 上使用。如果已在其他 CVM 上激活，则无法在当前 CVM 上重复激活。

Q3：激活时提示 License 过期怎么办？​

License过期提示

A： 请前往 License 续期指南 完成续期操作。

版本升级​

Q4：私有化部署版本升级是否会影响原有业务数据？​

A： 不会影响。升级过程会保留所有业务数据，请按照 版本升级指南 的步骤操作即可。

网络配置​

Q5：服务器未安装 HTTPS 证书导致安装失败如何解决？​

A： 可以使用以下命令跳过 SSL/TLS 证书验证：

wget --no-check-certificate http://xxxx

Q6：是否可以指定内网 IP 作为访问地址？​

A： 可以。默认使用公网 IP 访问，如需使用内网 IP，请参考 端口号及白名单 IP 配置 指定内网地址：

http://xxx.xxx.x.x:80

格式说明：协议 + 地址 + 端口

数据库配置​

Q7：自定义 MySQL 配置后，重启平台服务提示 Access denied 怎么办？​

MySQL连接错误

A： 请检查 config.yaml 文件中输入的 MySQL 信息在当前机器是否能正常连通。

排查步骤：

  1. 验证 MySQL 服务是否正常运行
  2. 检查用户名和密码是否正确
  3. 确认网络连接是否畅通
  4. 验证数据库权限配置

Q8：安装时 init-env 报错如何解决？​

init-env错误

分析： 自定义 MySQL（8.0 以上版本）不兼容导致的错误。

可通过以下命令查看详细日志：

docker logs -f init-env

详细错误日志

解决方案： 在外部 MySQL 中添加以下配置：

[client]
default_character_set = utf8mb4

[mysql]
default-character-set=utf8mb4

[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci
sql_mode = ALLOW_INVALID_DATES
explicit_defaults_for_timestamp = OFF

Q9：lcap-service 服务一直重启，日志报错如何处理？​

lcap-service错误

分析： 通常是外部数据库配置不满足要求导致的。

解决方案： 请按照 MySQL 服务器配置要求 修改 MySQL 配置。

容器服务​

Q10：安装报错 "容器名称冲突" 如何解决？​

错误信息：

Conflict. The container name "/mysql" is already in use by container

分析： 当前虚拟机上已存在同名的 MySQL Docker 容器。

解决方案：

Q11：安装报错 "端口被占用" 如何解决？​

错误信息：

Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use

分析： 当前虚拟机的 80 端口已被其他服务占用。

解决方案：

  • 方案一：停止占用 80 端口的服务
  • 方案二：在安装配置页面的访问地址中填写未被占用的端口

Q12：Docker 服务未启动导致安装失败如何解决？​

错误信息：

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

分析： 服务器已安装 Docker，但未启动 Docker 服务。

解决方案：

sudo systemctl start docker
sudo systemctl enable docker

安装环境​

Q13：Docker 安装失败如何解决？​

错误信息：

WEDA STEP 0: install docker Docker 未安装，开始安装 Docker 使用 yum 安装 Docker

分析： 服务器使用 yum 安装时可能因为 yum 源缺少对应资源导致下载失败。

解决方案： 更换镜像源手动安装 Docker，参考文档：搭建 Docker

Q14：清理任务执行失败如何处理？​

错误信息：

exec the task failed: WEDA STEP 5: clean up，Warning Configuration file /data/tencent/weda/docker-compose.yaml not found. Skipping docker-compose command.

分析： 执行清理任务时，仍有服务未停止。

解决方案：

  1. 停止所有正在运行的服务：
    docker ps -q | xargs -r docker stop
  2. 重新执行安装

集群部署​

Q15：集群部署时报错如何解决？​

集群部署错误

A： 请检查 License 类型，集群部署功能目前仅支持企业版 License。

应用发布​

Q16：应用一直处于发布中状态或发布失败无法结束怎么办？​

分析： 通常是 CI/CD 任务卡死导致的。

解决方案： 通过数据库操作清理卡死的部署记录：

# xxx 为应用 ID
SELECT * FROM deploy_history WHERE appId="xxx" ORDER BY id DESC;

# 查询出问题记录后，删除该记录即可
注意

执行数据库操作前请务必备份相关数据，避免误操作造成数据丢失。

功能使用问题​

文件存储​

Q17：文件/图片上传组件是否支持上传到自定义存储桶？​

A： 支持。请参考 自定义 S3 对象存储配置指南 进行配置。

支持的存储类型：

  • 腾讯云 COS
  • AWS S3
  • 兼容 S3 协议的其他对象存储服务

功能对比​

Q18：微搭私有部署版和公有云版本有哪些功能差异？​

A： 详细的功能差异对比请参考 能力对比清单。

主要差异包括：

  • 部署方式和环境要求
  • 某些云服务集成功能
  • 数据存储和备份策略
  • 技术支持服务范围

服务卡顿​

Q19: 应用卡顿，系统异常出现构建错误，进入不了系统，该如何处理？​

A： 请检查系统负载情况，可能是因为负载过高，80%-90%左右负载时，会出现服务卡顿，请扩容系统CPU/内存或磁盘。

获取更多帮助​

如果以上解答未能解决您的问题，您可以：

  1. 查看详细文档：访问 微搭私有部署文档中心 获取更多信息
  2. 联系技术支持：通过官方渠道提交技术支持请求
  3. 社区交流：参与微搭开发者社区讨论
提交问题时的建议

为了更快速地解决问题，建议您在提交问题时提供：

  • 详细的错误信息和截图
  • 系统环境信息（操作系统、Docker 版本等）
  • 操作步骤和复现方法
  • 相关的日志文件