核心参考项目：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 for Windows4.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 官方页面：
在 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 ps2. WSL 无法启动
PowerShell 管理员执行：
wsl --shutdown然后：
wsl3. 端口占用
修改：
nano .env修改：
SERVER_PORT=8081然后重启：
docker compose down
docker compose up -d第十九步：推荐学习内容
建议学习：
-
Docker
-
Linux
-
WSL2
-
Git
-
Docker Compose
-
AI API Gateway
-
Codex CLI