在已有 Docker Compose 环境中部署 MoeKoeMusic
in 默认分类 with 0 comment
在已有 Docker Compose 环境中部署 MoeKoeMusic
in 默认分类 with 0 comment


本文介绍如何在已经运行 Zoraxy 的 VPS 上，通过 Docker Compose 部署 MoeKoeMusic，并使用 Zoraxy 配置域名和 HTTPS 访问。

本文假设：

MoeKoeMusic 官方 Web 端 Docker 配置使用前端端口 8080，API 在容器内部使用 6521 端口。项目源码和部署方式请以官方仓库为准。

一、目录准备

建议将 Compose 文件和 MoeKoeMusic 源码放在同一个目录中，例如：

/opt/web-stack/
├── docker-compose.yml
├── MoeKoeMusic/
└── web/
    └── zoraxy/

如果还没有下载源码，在 VPS 上执行：

cd /opt/web-stack
git clone --depth=1 https://github.com/MoeKoeMusic/MoeKoeMusic.git

将 /opt/web-stack 替换为自己的实际部署目录。

二、修改 docker-compose.yml

在现有 services: 下新增 moekoe-music 服务：

  moekoe-music:
    container_name: moekoe-music
    restart: unless-stopped
    build:
      context: ./MoeKoeMusic
      dockerfile: Dockerfile
    environment:
      PORT: "6521"
      platform: "lite"
    expose:
      - "8080"
    networks:
      - shared-network

Compose 文件底部应继续保留已有网络配置：

networks:
  shared-network:

其中，context: ./MoeKoeMusic 表示使用同级目录中的源码构建镜像，expose 只在 Docker 网络内部开放 8080，不会直接开放到公网。

为什么不使用 ports？

由于 Zoraxy 已经负责监听宿主机的 80 和 443，MoeKoeMusic 不需要再映射公网端口。这样可以避免端口冲突，并统一由 Zoraxy 管理域名、HTTPS 和反向代理。

如果确实需要临时通过 VPS_IP:8080 访问，也可以改为：

    ports:
      - "8080:8080"

但生产环境通常不建议这样做。

三、首次构建和启动

进入 Compose 文件所在目录：

cd /opt/web-stack

构建并启动 MoeKoeMusic：

docker compose build moekoe-music
docker compose up -d moekoe-music

查看容器状态：

docker compose ps

查看启动日志：

docker compose logs -f --tail=100 moekoe-music

看到前端服务正常启动后，可以按 Ctrl+C 退出日志查看，不会停止容器。

四、在 Zoraxy 中配置反向代理

假设准备使用以下域名：

music.example.com

在 Zoraxy 中新增反向代理，目标填写：

域名：music.example.com
上游地址：http://moekoe-music:8080

这里的 moekoe-music 是 Docker 容器名。因为两个服务都加入了 shared-network，Zoraxy 可以通过容器名访问 MoeKoeMusic。

然后在 Zoraxy 中为该域名申请或配置 HTTPS 证书，并将 HTTP 请求重定向到 HTTPS。

浏览器访问：

https://music.example.com

五、源码更新后的同步流程

以后 MoeKoeMusic 发布源码更新时，进入部署目录执行：

cd /opt/web-stack
git -C MoeKoeMusic pull --ff-only
docker compose up -d --build moekoe-music

这几条命令依次完成：

  1. 拉取 GitHub 最新源码；
  2. 根据新源码重新构建镜像；
  3. 用新镜像重新创建 MoeKoeMusic 容器。

更新后检查状态和日志：

docker compose ps
docker compose logs -f --tail=100 moekoe-music

Zoraxy 和 sing-box 不会因为只更新 moekoe-music 而被重新部署。

六、依赖或缓存异常时的处理

如果更新后出现依赖安装异常、旧文件残留或构建结果不符合预期，可以执行无缓存构建：

cd /opt/web-stack
docker compose build --no-cache moekoe-music
docker compose up -d moekoe-music

无缓存构建会重新下载依赖，耗时通常更长，日常更新不需要默认使用。

七、更新前检查本地修改

在执行 git pull 前，建议先查看源码目录状态：

git -C MoeKoeMusic status

如果本地修改需要保留，应先提交或备份。不要直接使用强制覆盖命令。

确认本地修改完全不需要保留时，才可以执行：

git -C MoeKoeMusic restore .
git -C MoeKoeMusic pull --ff-only
docker compose up -d --build moekoe-music

八、常见问题

1. 容器无法启动

查看完整日志：

docker compose logs --tail=200 moekoe-music

确认 VPS 的 Node.js 构建环境、Docker 磁盘空间以及网络连接正常。官方 Dockerfile 当前使用 Node.js 20 构建。

2. Zoraxy 找不到上游服务

确认两个容器都加入了同一个网络：

docker network inspect shared-network

还可以进入 Zoraxy 容器测试 DNS 解析：

docker exec -it zoraxy ping -c 1 moekoe-music

如果容器名无法解析，检查 Compose 中的网络名称和服务配置。

3. 页面能打开，但 API 请求失败

确认 Zoraxy 的上游地址是：

http://moekoe-music:8080

不要将 API 上游单独配置为宿主机的 6521。MoeKoeMusic 的前端 Nginx 会在容器内部把 /api/ 请求转发到 API 服务。

4. 端口冲突

MoeKoeMusic 只使用 Docker 内部的 8080 和 6521 时，不会与现有的 80、443、8000、8800–8820 冲突。只有在添加 ports 时，才需要检查宿主机端口是否已被占用。

九、安全注意事项

参考资料

本文由 weiwuji 创作，采用 知识共享署名4.0 国际许可协议进行许可。
本站文章除注明转载/出处外，均为本站原创或翻译，转载前请务必署名。

→ ↓ ↑
Responses