前言Sub2API 是一款功能强大的大模型 API 聚合管理工具支持接入几十家主流大模型厂商提供统一的 OpenAI 兼容接口方便个人和小团队统一管理多渠道密钥、用量统计、额度分配。本教程基于 Windows 10 家庭版全程实测使用 Docker 容器化部署无需手动配置数据库、运行环境同时整理了国内网络环境下的所有常见坑点和解决方案跟着步骤走即可一次部署成功。适用人群Windows 10 用户家庭版/专业版均可想本地部署 Sub2API 自用的用户不想折腾复杂运行环境的新手一、前置准备1.1 系统要求Windows 10 版本 2004 及以上内部版本 19041CPU 支持并开启硬件虚拟化VT-x / AMD-V至少 2GB 可用内存推荐 4GB 以上1.2 提前确认硬件虚拟化这是最容易被忽略的一步未开启的话 Docker 无法正常运行。按下Ctrl Shift Esc打开任务管理器切换到「性能」选项卡点击左侧「CPU」在右侧参数中找到「虚拟化」显示已启用即可如果显示「已禁用」需要重启电脑进入 BIOS开启Intel Virtualization TechnologyIntel CPU或SVM ModeAMD CPU二、配置 WSL 2 环境Docker Desktop for Windows 依赖 WSL 2 作为后端必须先配置好 WSL 环境。2.1 开启系统功能两种方式任选其一方式一图形界面操作按下Win R输入optionalfeatures.exe回车在弹出的窗口中勾选以下两项✅ 适用于 Linux 的 Windows 子系统✅ 虚拟机平台点击确定等待系统配置完成后重启电脑方式二命令行操作管理员身份右键开始菜单选择「Windows PowerShell (管理员)」依次执行两条命令dism/online/enable-feature/featurename:Microsoft-Windows-Subsystem-Linux/all/norestart dism/online/enable-feature/featurename:VirtualMachinePlatform/all/norestart执行完成后重启电脑2.2 安装 WSL 2 Linux 内核更新包Win10 自带的 WSL 内核版本较低必须手动更新1.1. 下载官方内核安装包国内可直接访问WSL2 Linux 内核更新包 x641.2. 百度网盘地址链接wsl_update_x64.msi 提取码: 3s3n双击运行安装包一路下一步完成安装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.msixbundle1.2 百度网盘地址链接Microsoft.WSL_2.7.8.0_x64_ARM64.msixbundle: 提取码: zag62. 双击下载的文件点击「安装」等待完成3. 重启电脑后执行wsl --version能输出版本信息即为成功 避坑提示不需要手动安装 Ubuntu 等 Linux 发行版Docker Desktop 会自动创建专用的 WSL 发行版来运行容器单独安装 Ubuntu 不仅多余还会占用额外空间。三、安装 Docker Desktop3.1 下载安装包官方下载地址国内可访问Docker Desktop for Windows百度网盘地址链接Docker Desktop Installer.exe 提取码: eaee3.2 安装步骤双击运行安装包务必勾选「Use WSL 2 instead of Hyper-V」默认勾选不要取消点击 OK 等待安装完成按照提示重启电脑3.3 配置国内镜像加速必做国内网络直接拉取 Docker 镜像大概率会超时失败必须配置镜像源。启动 Docker Desktop跳过登录选择「Continue without signing in」点击右上角齿轮图标进入「Settings」左侧菜单选择「Docker Engine」在配置框中添加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]}点击右下角「Apply restart」等待 Docker 重启生效验证方式重启后在 PowerShell 执行docker info末尾能看到配置的镜像地址即为成功。四、部署 Sub2API4.1 创建部署目录在电脑非系统盘比如 D 盘、E 盘新建一个文件夹命名为sub2api。⚠️ 注意文件夹路径不要包含中文和空格避免后续出现莫名报错。4.2 编写 docker-compose.yml 配置文件进入sub2api文件夹先开启文件扩展名显示点击顶部「查看」选项卡勾选「文件扩展名」空白处右键 → 新建 → 文本文档重命名为docker-compose.yml确认后缀是.yml不是.txt用记事本或 VS Code 打开文件粘贴以下完整配置services:sub2api:image:weishaw/sub2api:latestcontainer_name:sub2apirestart:unless-stoppedports:-8080:8080volumes:-./data/sub2api:/app/dataenvironment:-AUTO_SETUPtrue-TZAsia/Shanghai-SERVER_MODErelease-DATABASE_HOSTpostgres-DATABASE_PORT5432-DATABASE_USERsub2api-DATABASE_PASSWORDsub2api_2026-DATABASE_DBNAMEsub2api-REDIS_HOSTredis-REDIS_PORT6379-REDIS_PASSWORDredis_2026-ADMIN_EMAILadminsub2api.local-ADMIN_PASSWORDadmin123456-SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTPtrue-SECURITY_URL_ALLOWLIST_ALLOWED_HOSTS*depends_on:-postgres-redisnetworks:-sub2api-networkpostgres:image:postgres:15-alpinecontainer_name:sub2api-postgresrestart:unless-stoppedenvironment:-POSTGRES_USERsub2api-POSTGRES_PASSWORDsub2api_2026-POSTGRES_DBsub2api-TZAsia/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 启动服务在sub2api文件夹顶部的地址栏中输入cmd并回车自动打开当前目录的命令行窗口执行启动命令docker compose up-d等待镜像拉取和容器启动看到三个服务都显示Started即为启动成功五、验证与基础使用5.1 查看容器运行状态执行命令确认所有容器正常运行docker composeps三个容器的STATUS列都显示Up状态即为正常。5.2 访问管理后台等待 10~20 秒首次启动需要初始化数据库打开浏览器访问http://localhost:8080默认管理员账号邮箱adminsub2api.local密码admin123456 安全提示登录后第一时间进入「我的账户」修改默认密码5.3 基础使用流程添加渠道左侧菜单「渠道管理」→ 添加渠道填入你的大模型 API Key支持 OpenAI、DeepSeek、豆包、通义千问等几十家厂商创建 API 密钥左侧菜单「API 密钥」→ 创建密钥生成属于你的调用密钥对接使用在支持 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 端口排查步骤执行docker compose ps确认 sub2api 容器状态是 Up执行docker compose logs sub2api查看启动日志是否有报错检查 8080 端口是否被其他程序占用关闭 Windows 防火墙测试或手动放行 8080 端口4. WSL 命令执行报错或 Docker 识别不到 WSL解决方案执行wsl --shutdown关闭所有 WSL重新安装 WSL2 内核更新包升级 WSL 到最新版参考 2.4 节重启电脑后再试5. 要不要手动安装 Ubuntu 发行版不需要。Docker Desktop 会自动创建docker-desktop和docker-desktop-data两个专用发行版完全满足运行需求单独安装 Ubuntu 只会占用额外磁盘空间。八、写在最后整个部署过程最容易踩坑的地方就是 WSL 环境配置和国内网络问题按照本教程的步骤一步步来基本都能一次部署成功。部署完成后你就拥有了一个本地运行的私有 API 聚合网关统一管理所有大模型渠道方便在各种客户端、插件中使用。如果教程对你有帮助欢迎分享给更多有需要的朋友~ Windows 10 环境下 Docker 部署 Sub2API 完整教程（避坑版）
前言Sub2API 是一款功能强大的大模型 API 聚合管理工具支持接入几十家主流大模型厂商提供统一的 OpenAI 兼容接口方便个人和小团队统一管理多渠道密钥、用量统计、额度分配。本教程基于 Windows 10 家庭版全程实测使用 Docker 容器化部署无需手动配置数据库、运行环境同时整理了国内网络环境下的所有常见坑点和解决方案跟着步骤走即可一次部署成功。适用人群Windows 10 用户家庭版/专业版均可想本地部署 Sub2API 自用的用户不想折腾复杂运行环境的新手一、前置准备1.1 系统要求Windows 10 版本 2004 及以上内部版本 19041CPU 支持并开启硬件虚拟化VT-x / AMD-V至少 2GB 可用内存推荐 4GB 以上1.2 提前确认硬件虚拟化这是最容易被忽略的一步未开启的话 Docker 无法正常运行。按下Ctrl Shift Esc打开任务管理器切换到「性能」选项卡点击左侧「CPU」在右侧参数中找到「虚拟化」显示已启用即可如果显示「已禁用」需要重启电脑进入 BIOS开启Intel Virtualization TechnologyIntel CPU或SVM ModeAMD CPU二、配置 WSL 2 环境Docker Desktop for Windows 依赖 WSL 2 作为后端必须先配置好 WSL 环境。2.1 开启系统功能两种方式任选其一方式一图形界面操作按下Win R输入optionalfeatures.exe回车在弹出的窗口中勾选以下两项✅ 适用于 Linux 的 Windows 子系统✅ 虚拟机平台点击确定等待系统配置完成后重启电脑方式二命令行操作管理员身份右键开始菜单选择「Windows PowerShell (管理员)」依次执行两条命令dism/online/enable-feature/featurename:Microsoft-Windows-Subsystem-Linux/all/norestart dism/online/enable-feature/featurename:VirtualMachinePlatform/all/norestart执行完成后重启电脑2.2 安装 WSL 2 Linux 内核更新包Win10 自带的 WSL 内核版本较低必须手动更新1.1. 下载官方内核安装包国内可直接访问WSL2 Linux 内核更新包 x641.2. 百度网盘地址链接wsl_update_x64.msi 提取码: 3s3n双击运行安装包一路下一步完成安装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.msixbundle1.2 百度网盘地址链接Microsoft.WSL_2.7.8.0_x64_ARM64.msixbundle: 提取码: zag62. 双击下载的文件点击「安装」等待完成3. 重启电脑后执行wsl --version能输出版本信息即为成功 避坑提示不需要手动安装 Ubuntu 等 Linux 发行版Docker Desktop 会自动创建专用的 WSL 发行版来运行容器单独安装 Ubuntu 不仅多余还会占用额外空间。三、安装 Docker Desktop3.1 下载安装包官方下载地址国内可访问Docker Desktop for Windows百度网盘地址链接Docker Desktop Installer.exe 提取码: eaee3.2 安装步骤双击运行安装包务必勾选「Use WSL 2 instead of Hyper-V」默认勾选不要取消点击 OK 等待安装完成按照提示重启电脑3.3 配置国内镜像加速必做国内网络直接拉取 Docker 镜像大概率会超时失败必须配置镜像源。启动 Docker Desktop跳过登录选择「Continue without signing in」点击右上角齿轮图标进入「Settings」左侧菜单选择「Docker Engine」在配置框中添加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]}点击右下角「Apply restart」等待 Docker 重启生效验证方式重启后在 PowerShell 执行docker info末尾能看到配置的镜像地址即为成功。四、部署 Sub2API4.1 创建部署目录在电脑非系统盘比如 D 盘、E 盘新建一个文件夹命名为sub2api。⚠️ 注意文件夹路径不要包含中文和空格避免后续出现莫名报错。4.2 编写 docker-compose.yml 配置文件进入sub2api文件夹先开启文件扩展名显示点击顶部「查看」选项卡勾选「文件扩展名」空白处右键 → 新建 → 文本文档重命名为docker-compose.yml确认后缀是.yml不是.txt用记事本或 VS Code 打开文件粘贴以下完整配置services:sub2api:image:weishaw/sub2api:latestcontainer_name:sub2apirestart:unless-stoppedports:-8080:8080volumes:-./data/sub2api:/app/dataenvironment:-AUTO_SETUPtrue-TZAsia/Shanghai-SERVER_MODErelease-DATABASE_HOSTpostgres-DATABASE_PORT5432-DATABASE_USERsub2api-DATABASE_PASSWORDsub2api_2026-DATABASE_DBNAMEsub2api-REDIS_HOSTredis-REDIS_PORT6379-REDIS_PASSWORDredis_2026-ADMIN_EMAILadminsub2api.local-ADMIN_PASSWORDadmin123456-SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTPtrue-SECURITY_URL_ALLOWLIST_ALLOWED_HOSTS*depends_on:-postgres-redisnetworks:-sub2api-networkpostgres:image:postgres:15-alpinecontainer_name:sub2api-postgresrestart:unless-stoppedenvironment:-POSTGRES_USERsub2api-POSTGRES_PASSWORDsub2api_2026-POSTGRES_DBsub2api-TZAsia/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 启动服务在sub2api文件夹顶部的地址栏中输入cmd并回车自动打开当前目录的命令行窗口执行启动命令docker compose up-d等待镜像拉取和容器启动看到三个服务都显示Started即为启动成功五、验证与基础使用5.1 查看容器运行状态执行命令确认所有容器正常运行docker composeps三个容器的STATUS列都显示Up状态即为正常。5.2 访问管理后台等待 10~20 秒首次启动需要初始化数据库打开浏览器访问http://localhost:8080默认管理员账号邮箱adminsub2api.local密码admin123456 安全提示登录后第一时间进入「我的账户」修改默认密码5.3 基础使用流程添加渠道左侧菜单「渠道管理」→ 添加渠道填入你的大模型 API Key支持 OpenAI、DeepSeek、豆包、通义千问等几十家厂商创建 API 密钥左侧菜单「API 密钥」→ 创建密钥生成属于你的调用密钥对接使用在支持 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 端口排查步骤执行docker compose ps确认 sub2api 容器状态是 Up执行docker compose logs sub2api查看启动日志是否有报错检查 8080 端口是否被其他程序占用关闭 Windows 防火墙测试或手动放行 8080 端口4. WSL 命令执行报错或 Docker 识别不到 WSL解决方案执行wsl --shutdown关闭所有 WSL重新安装 WSL2 内核更新包升级 WSL 到最新版参考 2.4 节重启电脑后再试5. 要不要手动安装 Ubuntu 发行版不需要。Docker Desktop 会自动创建docker-desktop和docker-desktop-data两个专用发行版完全满足运行需求单独安装 Ubuntu 只会占用额外磁盘空间。八、写在最后整个部署过程最容易踩坑的地方就是 WSL 环境配置和国内网络问题按照本教程的步骤一步步来基本都能一次部署成功。部署完成后你就拥有了一个本地运行的私有 API 聚合网关统一管理所有大模型渠道方便在各种客户端、插件中使用。如果教程对你有帮助欢迎分享给更多有需要的朋友~