当前位置： 首页 > news >正文

Windows 10 环境下 Docker 部署 Sub2API 完整教程（避坑版）

news 2026/7/1 16:13:06

前言

Sub2API 是一款功能强大的大模型 API 聚合管理工具，支持接入几十家主流大模型厂商，提供统一的 OpenAI 兼容接口，方便个人和小团队统一管理多渠道密钥、用量统计、额度分配。

本教程基于 Windows 10 家庭版全程实测，使用 Docker 容器化部署，无需手动配置数据库、运行环境，同时整理了国内网络环境下的所有常见坑点和解决方案，跟着步骤走即可一次部署成功。

适用人群：

  • Windows 10 用户（家庭版/专业版均可）
  • 想本地部署 Sub2API 自用的用户
  • 不想折腾复杂运行环境的新手

一、前置准备

1.1 系统要求

  • Windows 10 版本 2004 及以上（内部版本 19041+）
  • CPU 支持并开启硬件虚拟化（VT-x / AMD-V）
  • 至少 2GB 可用内存，推荐 4GB 以上

1.2 提前确认：硬件虚拟化

这是最容易被忽略的一步，未开启的话 Docker 无法正常运行。

  1. 按下Ctrl + Shift + Esc打开任务管理器
  2. 切换到「性能」选项卡，点击左侧「CPU」
  3. 在右侧参数中找到「虚拟化」，显示已启用即可
  4. 如果显示「已禁用」，需要重启电脑进入 BIOS，开启Intel Virtualization Technology（Intel CPU）或SVM Mode（AMD CPU）

二、配置 WSL 2 环境

Docker Desktop for Windows 依赖 WSL 2 作为后端，必须先配置好 WSL 环境。

2.1 开启系统功能

两种方式任选其一：

方式一：图形界面操作
  1. 按下Win + R，输入optionalfeatures.exe回车
  2. 在弹出的窗口中，勾选以下两项：
    • ✅ 适用于 Linux 的 Windows 子系统
    • ✅ 虚拟机平台
  3. 点击确定，等待系统配置完成后重启电脑
方式二：命令行操作（管理员身份）
  1. 右键开始菜单，选择「Windows PowerShell (管理员)」
  2. 依次执行两条命令：
dism/online/enable-feature/featurename:Microsoft-Windows-Subsystem-Linux/all/norestart dism/online/enable-feature/featurename:VirtualMachinePlatform/all/norestart
  1. 执行完成后重启电脑

2.2 安装 WSL 2 Linux 内核更新包

Win10 自带的 WSL 内核版本较低，必须手动更新：
1.1. 下载官方内核安装包（国内可直接访问）：

WSL2 Linux 内核更新包 x64

1.2. 百度网盘地址：
链接：wsl_update_x64.msi 提取码: 3s3n

  1. 双击运行安装包，一路下一步完成安装

2.3 设置 WSL 默认版本为 2

打开管理员 PowerShell，执行命令：

wsl--set-default-version 2

显示「操作成功完成」即可。

2.4 （推荐）升级 WSL 到最新版

Win10 自带的 WSL 命令行工具版本较旧，不支持wsl --version命令，也可能导致 Docker 识别异常，建议升级。

离线升级方式

1.1 下载最新版 WSL 安装包（国内加速地址）：

https://mirror.ghproxy.com/https://github.com/microsoft/WSL/releases/latest/download/Microsoft.WSL_x64.msixbundle

1.2 百度网盘地址：
链接：Microsoft.WSL_2.7.8.0_x64_ARM64.msixbundle: 提取码: zag6
2. 双击下载的文件，点击「安装」等待完成
3. 重启电脑后，执行wsl --version能输出版本信息即为成功

💡 避坑提示：不需要手动安装 Ubuntu 等 Linux 发行版！Docker Desktop 会自动创建专用的 WSL 发行版来运行容器，单独安装 Ubuntu 不仅多余还会占用额外空间。

三、安装 Docker Desktop

3.1 下载安装包

官方下载地址（国内可访问）：

Docker Desktop for Windows

百度网盘地址：
链接：Docker Desktop Installer.exe 提取码: eaee

3.2 安装步骤

  1. 双击运行安装包
  2. 务必勾选「Use WSL 2 instead of Hyper-V」（默认勾选，不要取消）
  3. 点击 OK 等待安装完成，按照提示重启电脑

3.3 配置国内镜像加速（必做）

国内网络直接拉取 Docker 镜像大概率会超时失败，必须配置镜像源。

  1. 启动 Docker Desktop，跳过登录（选择「Continue without signing in」）
  2. 点击右上角齿轮图标进入「Settings」
  3. 左侧菜单选择「Docker Engine」
  4. 在配置框中添加registry-mirrors字段，完整配置如下：
{"builder":{"gc":{"defaultKeepStorage":"20GB","enabled":true}},"experimental":false,"registry-mirrors":["https://docker.mirrors.ustc.edu.cn","https://hub-mirror.c.163.com","https://mirror.baidubce.com"]}
  1. 点击右下角「Apply & restart」，等待 Docker 重启生效

验证方式：重启后在 PowerShell 执行docker info，末尾能看到配置的镜像地址即为成功。

四、部署 Sub2API

4.1 创建部署目录

在电脑非系统盘（比如 D 盘、E 盘）新建一个文件夹，命名为sub2api。

⚠️ 注意：文件夹路径不要包含中文和空格，避免后续出现莫名报错。

4.2 编写 docker-compose.yml 配置文件

  1. 进入sub2api文件夹
  2. 先开启文件扩展名显示：点击顶部「查看」选项卡，勾选「文件扩展名」
  3. 空白处右键 → 新建 → 文本文档，重命名为docker-compose.yml（确认后缀是.yml不是.txt）
  4. 用记事本或 VS Code 打开文件，粘贴以下完整配置：
services:sub2api:image:weishaw/sub2api:latestcontainer_name:sub2apirestart:unless-stoppedports:-"8080:8080"volumes:-./data/sub2api:/app/dataenvironment:-AUTO_SETUP=true-TZ=Asia/Shanghai-SERVER_MODE=release-DATABASE_HOST=postgres-DATABASE_PORT=5432-DATABASE_USER=sub2api-DATABASE_PASSWORD=sub2api_2026-DATABASE_DBNAME=sub2api-REDIS_HOST=redis-REDIS_PORT=6379-REDIS_PASSWORD=redis_2026-ADMIN_EMAIL=admin@sub2api.local-ADMIN_PASSWORD=admin123456-SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=true-SECURITY_URL_ALLOWLIST_ALLOWED_HOSTS=*depends_on:-postgres-redisnetworks:-sub2api-networkpostgres:image:postgres:15-alpinecontainer_name:sub2api-postgresrestart:unless-stoppedenvironment:-POSTGRES_USER=sub2api-POSTGRES_PASSWORD=sub2api_2026-POSTGRES_DB=sub2api-TZ=Asia/Shanghaivolumes:-./data/postgres:/var/lib/postgresql/datanetworks:-sub2api-networkredis:image:redis:7-alpinecontainer_name:sub2api-redisrestart:unless-stoppedcommand:redis-server--requirepass redis_2026volumes:-./data/redis:/datanetworks:-sub2api-networknetworks:sub2api-network:driver:bridge

配置说明：

  • 包含 Sub2API 主程序、PostgreSQL 数据库、Redis 缓存三个服务
  • 数据全部持久化保存在./data目录下，删除容器不会丢失数据
  • 默认端口 8080，可根据需要修改
  • 数据库密码、管理员账号密码建议自行修改，提升安全性

4.3 启动服务

  1. 在sub2api文件夹顶部的地址栏中，输入cmd并回车，自动打开当前目录的命令行窗口
  2. 执行启动命令：
docker compose up-d
  1. 等待镜像拉取和容器启动，看到三个服务都显示Started即为启动成功

五、验证与基础使用

5.1 查看容器运行状态

执行命令确认所有容器正常运行：

docker composeps

三个容器的STATUS列都显示Up状态即为正常。

5.2 访问管理后台

等待 10~20 秒（首次启动需要初始化数据库），打开浏览器访问：

http://localhost:8080

默认管理员账号：

  • 邮箱：admin@sub2api.local
  • 密码：admin123456

🔒 安全提示：登录后第一时间进入「我的账户」修改默认密码！

5.3 基础使用流程

  1. 添加渠道：左侧菜单「渠道管理」→ 添加渠道，填入你的大模型 API Key（支持 OpenAI、DeepSeek、豆包、通义千问等几十家厂商）
  2. 创建 API 密钥：左侧菜单「API 密钥」→ 创建密钥，生成属于你的调用密钥
  3. 对接使用：在支持 OpenAI 格式的应用中，将接口地址改为http://localhost:8080/v1，填入你生成的密钥即可使用

六、日常运维命令

所有命令都需要在sub2api目录下的命令行中执行：

命令作用
docker compose up -d启动/更新所有服务
docker compose stop停止所有服务
docker compose restart重启所有服务
docker compose logs sub2api查看 Sub2API 运行日志（排错用）
docker compose pull拉取最新镜像（更新版本用）

数据备份

所有配置、用户、账单数据都保存在目录下的data文件夹中，定期复制备份这个文件夹即可；重装 Docker 或系统后，将备份文件夹放回原目录就能恢复所有数据。

七、常见问题与解决方案

1. Docker 启动报错：Virtualization support not detected

  • 原因：CPU 硬件虚拟化未开启
  • 解决方案：重启电脑进入 BIOS，开启 VT-x / SVM Mode，具体方法参考本文 1.2 节

2. 镜像拉取失败：connectex: 连接尝试失败

  • 原因：国内网络无法访问 Docker 官方镜像仓库
  • 解决方案：参考本文 3.3 节配置国内镜像加速源；如果有代理工具，也可以在 Docker 设置的「Proxies」中配置代理

3. 启动后浏览器无法访问 8080 端口

  • 排查步骤：
    1. 执行docker compose ps确认 sub2api 容器状态是 Up
    2. 执行docker compose logs sub2api查看启动日志，是否有报错
    3. 检查 8080 端口是否被其他程序占用
    4. 关闭 Windows 防火墙测试，或手动放行 8080 端口

4. WSL 命令执行报错，或 Docker 识别不到 WSL

  • 解决方案：
    1. 执行wsl --shutdown关闭所有 WSL
    2. 重新安装 WSL2 内核更新包
    3. 升级 WSL 到最新版（参考 2.4 节）
    4. 重启电脑后再试

5. 要不要手动安装 Ubuntu 发行版？

  • 不需要。Docker Desktop 会自动创建docker-desktop和docker-desktop-data两个专用发行版，完全满足运行需求，单独安装 Ubuntu 只会占用额外磁盘空间。

八、写在最后

整个部署过程最容易踩坑的地方就是 WSL 环境配置和国内网络问题，按照本教程的步骤一步步来，基本都能一次部署成功。

部署完成后，你就拥有了一个本地运行的私有 API 聚合网关，统一管理所有大模型渠道，方便在各种客户端、插件中使用。

如果教程对你有帮助，欢迎分享给更多有需要的朋友~

http://www.gsyq.cn/news/1615368.html

相关文章：

  • ICM-42688-P与STM32L021K4在运动控制与工业监测中的应用
  • ncmdumpGUI：免费解锁网易云音乐加密NCM文件的终极Windows图形界面解决方案
  • AMD Ryzen处理器免费调试神器：5分钟学会SMU Debug Tool完整指南
  • Smithbox免费开源游戏修改工具：魂系游戏Mod制作的终极指南
  • 三步掌握pywencai：Python高效获取同花顺问财数据的实战指南
  • 终极指南：如何轻松实现Switch与WiiU《塞尔达传说》存档自由转换
  • 大厂是怎么监控 Java 项目的 01
  • 查英文论文时，谷歌学术入口、SCI文献和DOI信息可以这样配合使用
  • Linux 远程连接实操｜SSH、Xshell 与 Xftp 使用笔记
  • YOLOv10模型改进-注意力机制-第39篇：YOLOv10改进策略【注意力机制】| Transformer注意力机制
  • paperxie 文献综述智能创作神器｜四步流程搞定文献梳理，科研写稿不用硬熬
  • Sunshine游戏串流主机：构建跨平台游戏云生态的终极蓝图
  • JoyVASA 技术解析：把音频驱动人像动画拆成“运动生成 + LivePortrait 渲染”
  • AI产品形态五级分层架构体系
  • 软考高级系统规划与管理师认证信息整理
  • 持证玻璃防火门耐火构造与消防验收核查要点
  • 收藏！AI时代，程序员如何逆袭？小白也能学会的大模型应用指南
  • 百元耳机黑马实锤！水月雨 Pill 音乐胶囊，通勤办公游戏一副搞定
  • 《HarmonyOS技术精讲-Core File Kit》第3篇：文件读写——从文本到二进制数据
  • 双开钢制防火门五金配置、闭门器联动调试技术规范
  • 别被‘大功率’带偏，真正该看的是污水泵的过流能力与密封设计
  • 储能BMS微控制器选型难题怎么破：2026五大主流方案专业解析
  • SLO2016与STM32F446RE硬件协同设计与优化实践
  • Liquibase 入门指南：数据库版本控制的最佳实践
  • STM32与LV30模组打造高效低功耗条码识别系统
  • 万物沙石厂管理系统、万物水泥厂管理系统 重构建材全流程管理
  • 3步搞定音乐文件解锁：让加密音乐在任何设备自由播放
  • LangGraph核心揭秘：让AI「想一步、停一步、判断一步」的大模型学习之旅（收藏版）
  • Unity Profiler连接抖音开发者工具
  • 《HarmonyOS技术精讲-Core File Kit》第4篇：目录操作与文件遍历