使用 Docker 运行 Core稍难

字数统计:1.2k 字

阅读时长:4 分钟

🚨 警告

下面提供了两种方式进行 Docker 部署, 二选一即可！

如果你对两种方式的区别不了解，请使用选择 1

镜像特性

1. 轻量高效：原始镜像使用 astral/uv:python3.12-bookworm-slim，该镜像支持 linux/amd64, linux/arm64。
2. 环境完备：镜像使用 uv 构建 虚拟环境 默认已包含：pip, setuptools, wheel 等工具以及 Playwright & Chromium 浏览器环境，开箱即用。
3. 灵活配置：支持网络代理配置、python 包镜像源替换 等，可参考 环境设置 进行设置。

选择 1、使用 Docker 镜像部署

请先安装好 Docker

---

可通过如下指令拉取镜像并运行：

docker run -d \
  --name gsuid_core \
  --restart always \
  -p 8765:8765 \
  -v /opt/gscore_data:/gsuid_core/data \
  -v /opt/gscore_plugins:/gsuid_core/gsuid_core/plugins \
  -v gsuid_core_venv:/venv \
  docker.cnb.cool/gscore-mirror/gsuid_core:latest

在本地按照以上指令容器运行后，可直接进入localhost:8765/app进入核心的后台管理界面 相关文档见：网页控制台

镜像参数说明：

参数	功能
-d	后台运行：容器在后台持续执行。
--name gsuid_core	容器命名：方便后续通过名字进行停止或重启。
-p 8765:8765	端口映射：宿主机端口:容器端口，映射后方可访问后台。
-v /opt/gscore_data:/gsuid_core/data	数据持久化：重要!!! 存放玩家账号、数据库等核心资产，容器重建后数据不丢失。
-v /opt/gscore_plugins:/gsuid_core/gsuid_core/plugins	插件持久化：可在宿主机直接管理插件文件。
-v gsuid_core_venv:/venv	python 虚拟环境：使用命名卷来持久化存储容器内的 Python 虚拟环境。
--add-host host.docker.internal:host-gateway	映射宿主机 IP：这能让容器内部通过 host.docker.internal 这个域名直接访问宿主机的网络
-e UV_DEFAULT_INDEX=	Python 镜像源: 如 https://pypi.org/simple/
-e http_proxy=	HTTP 代理：如 http://host.docker.internal:7890（需开启代理软件 LAN 共享）。
-e https_proxy=	HTTPS 代理：同上。（git 代理需要单独设置，在高级操作指南下面有介绍）
-e no_proxy=	代理白名单：指定哪些地址不走代理。通常包含 localhost,127.0.0.1,cnb.cool 以及国内镜像源地址。

部分参数没有完全列出，有需要可参考环境设置 、 docker-compose进行设置。

选择 2、使用 Docker compose 从代码构建 docker 容器

特点：挂载本地代码到容器，无需等待镜像更新，直接使用 git:手动拉取 or 命令: core全部更新, 即可同步更新。

1. 拉取代码

# 方法一：从 GitHub 拉取
git clone https://github.com/Genshin-bots/gsuid_core.git

# 方法二：从 cnb.cool 拉取（国内镜像更快）
git clone https://cnb.cool/gscore-mirror/gsuid_core.git

cd gsuid_core

2. 创建配置文件（可选）

cp .env.example .env

💡 如需自定义配置，请编辑 .env 文件并取消注释相应配置

3. 启动服务

docker-compose up -d --build

4. 管理
   • 服务运行在端口 8765。
   • 启动后可通过 localhost:8765/app 进入核心的后台管理界面

---

高级操作指南

1. 网络代理配置

(注意：请确保代理软件开启了 "允许局域网连接/LAN" 模式)

容器内的全局代理（不包括 Git 代理） docker-compose 模式可在 .env 中添加：

GSCORE_HTTP_PROXY=http://host.docker.internal:7890
GSCORE_HTTPS_PROXY=http://host.docker.internal:7890

docker run 模式可增加 -e 参数

-e http_proxy=http://host.docker.internal:7890
-e https_proxy=http://host.docker.internal:7890

容器内设置 Git 代理

docker exec -it gsuid_core git config --global http.proxy http://host.docker.internal:7890

2. 配置 Python 镜像源（国内加速）

可运行仓库根目录的 check_pypi_mirrors.py 实测各镜像源的延迟与下载速度，脚本结尾会给出推荐（仅需 Python 标准库，macOS / Linux / Windows 均可运行）：

python3 check_pypi_mirrors.py

💡 测试完成后会直接给出推荐镜像源对应的启动命令（docker compose / docker run / 手动启动），复制执行即可。

将测得最快的镜像源填入配置，docker-compose 模式可在 .env 中设置：

GSCORE_PYTHON_INDEX=https://mirrors.aliyun.com/pypi/simple/

docker run 模式可增加 -e 参数：

-e UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/

3. 安装额外的 Python 包

如果你安装了第三方插件需要额外依赖：

docker exec -it gsuid_core uv pip install <包名>

4. python 环境重置 (解决依赖冲突)

如果更新镜像后报错，请执行以下命令彻底清理旧环境：

# docker-compose 模式
docker-compose down -v
docker-compose up -d --build

# docker run 模式
docker stop gsuid_core && docker rm gsuid_core
docker volume rm gsuid_core_venv
# 然后重新执行前面的 docker run 命令

(警告：这将删除 Python 虚拟环境卷（compose 模式为 venv-data，docker run 模式为 gsuid_core_venv），所有手动安装的包需要重新安装，但 data 游戏数据不会丢失)