核心参考项目：Wei-Shaw/sub2api GitHub 仓库 部署说明参考：Sub2API Docker 部署文档
适用于：
-
Windows 11
-
本地 AI 容器环境
-
WSL2 Ubuntu
-
Docker Desktop
-
Codex CLI
-
Sub2API
第一步：开启 Windows WSL2
1.1 以管理员身份打开 PowerShell
点击：
-
开始菜单
-
搜索：
PowerShell
右键：
以管理员身份运行
1.2 安装 WSL2
在管理员 PowerShell 输入：
wsl.exe –install
如果已经安装过，执行更新：
wsl.exe –update
安装完成后：
-
系统会自动下载 Ubuntu
-
重启电脑
微软官方 WSL 文档： Microsoft WSL 官方文档
第二步：初始化 Ubuntu
电脑重启后：
Windows 会自动打开 Ubuntu 终端。
第一次启动时会提示：
Enter new UNIX username:
输入：
admin
然后输入密码：
123456
再次确认密码：
123456
完成后进入 Ubuntu。
第三步：验证 WSL2 是否成功
在 Ubuntu 或 PowerShell 输入：
wsl –list –verbose
你应该看到：
NAME STATE VERSION
Ubuntu Running 2
如果 VERSION 显示为：
2
说明 WSL2 安装成功。
第四步：安装 Docker Desktop
打开 Docker 官网：
Docker Desktop 官网
下载安装：
Docker Desktop for Windows
4.1 Docker Desktop 设置
安装完成后：
打开 Docker Desktop。
进入：
Settings
→ Resources
→ WSL Integration
开启：
Ubuntu
然后点击：
Apply & Restart
第五步：Ubuntu 安装基础环境
进入 Ubuntu：
wsl
更新系统：
sudo apt update && sudo apt upgrade -y
输入密码：
123456
安装常用工具：
sudo apt install -y git curl wget unzip nano
第六步：安装 Node.js
推荐安装 Node.js 20：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash –
然后：
sudo apt install -y nodejs
验证：
node -v
npm -v
第七步：安装 Codex CLI
打开 OpenAI Codex 官方页面：
OpenAI Codex
在 Ubuntu 安装：
npm install -g @openai/codex
验证：
codex –version
登录：
codex login
浏览器会自动授权。
第八步：安装 Git 并克隆 Sub2API
进入 Ubuntu：
cd ~
克隆项目：
git clone https://github.com/Wei-Shaw/sub2api.git
进入目录：
cd sub2api
项目地址： Sub2API GitHub 仓库
第九步：使用 Docker 部署 Sub2API（推荐）
官方推荐 Docker Compose 部署。 (GitHub)
进入部署目录：
cd deploy
执行官方一键部署脚本：
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
该脚本会自动：
-
下载 docker-compose 配置
-
创建 .env
-
自动生成密钥
-
创建数据库目录
-
创建 Redis 目录
官方文档说明：(GitHub)
第十步：启动本地容器
启动容器：
docker compose -f docker-compose.local.yml up -d
查看运行状态：
docker ps
查看日志：
docker compose -f docker-compose.local.yml logs -f sub2api
第十一步：查看管理员密码
如果没有手动设置管理员密码：
执行：
docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"
系统会自动生成管理员密码。 (GitHub)
第十二步：打开 Web 管理后台
浏览器打开：这个地方建议端口号改成其他的，例如8787，防止和本地项目冲突
http://localhost:8080
默认管理员邮箱：
admin@sub2api.local
密码：
-
你设置的密码
-
或日志里自动生成的密码
第十三步：常用 Docker 命令
查看容器
docker ps
查看日志
docker compose -f docker-compose.local.yml logs -f
停止容器
docker compose -f docker-compose.local.yml down
重启容器
docker compose -f docker-compose.local.yml restart
第十四步：Windows 中进入 Ubuntu
以后每次进入 Ubuntu：
Windows 搜索：
Ubuntu
或者 PowerShell 输入：
wsl
第十五步：确认 Docker 与 WSL2 联动成功
Ubuntu 输入：
docker version
如果能看到：
Client:
Server:
说明：
-
Docker Desktop
-
WSL2
-
Ubuntu
已经成功联动。
第十六步：推荐目录结构
建议：
/home/admin/projects/
例如：
mkdir -p ~/projects
cd ~/projects
以后：
-
Git 项目
-
Docker 项目
-
Codex 项目
都放这里。
第十七步：推荐开发流程
推荐顺序：
Windows 11
↓
WSL2
↓
Ubuntu
↓
Docker Desktop
↓
Codex CLI
↓
Sub2API
这是目前 Windows 本地 AI 开发最稳定方案。
第十八步：常见问题
1. Docker 无法连接
重启：
Docker Desktop
然后：
docker ps
2. WSL 无法启动
PowerShell 管理员执行：
wsl –shutdown
然后：
wsl
3. 端口占用
修改：
nano .env
修改：
SERVER_PORT=8081
然后重启：
docker compose down
docker compose up -d
第十九步：推荐学习内容
建议学习：
-
Docker
-
Linux
-
WSL2
-
Git
-
Docker Compose
-
AI API Gateway
-
Codex CLI
官方参考资料
-
Sub2API GitHub 仓库
-
Sub2API Docker 部署文档
-
Sub2API 中文说明
-
Docker Desktop 官网
-
Microsoft WSL 官方文档
-
OpenAI Codex
