574 lines
13 KiB
Markdown
574 lines
13 KiB
Markdown
# IC Coder 认证系统实现文档
|
||
|
||
## 概述
|
||
|
||
本文档详细说明了 IC Coder 插件如何集成 VSCode Authentication API，实现用户登录功能，并在 VSCode 左下角账户区域显示登录状态。
|
||
|
||
## 架构设计
|
||
|
||
### 核心组件
|
||
|
||
1. **ICCoderAuthenticationProvider** - 认证提供者
|
||
2. **VSCode Authentication API** - VSCode 官方认证接口
|
||
3. **本地 HTTP 服务器** - 处理登录回调
|
||
4. **ICViewProvider** - 侧边栏视图（根据登录状态显示不同按钮）
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
用户点击登录
|
||
↓
|
||
调用 vscode.authentication.getSession()
|
||
↓
|
||
ICCoderAuthenticationProvider.createSession()
|
||
↓
|
||
启动本地 HTTP 服务器（动态端口）
|
||
↓
|
||
打开浏览器访问登录页面
|
||
↓
|
||
用户在网站完成登录
|
||
↓
|
||
网站重定向到 http://localhost:{port}/callback?token=xxx
|
||
↓
|
||
本地服务器接收 token
|
||
↓
|
||
创建 AuthenticationSession
|
||
↓
|
||
VSCode 左下角显示账户信息
|
||
```
|
||
|
||
## 详细实现
|
||
|
||
### 1. Authentication Provider 实现
|
||
|
||
文件：`src/services/icCoderAuthProvider.ts`
|
||
|
||
#### 1.1 类定义
|
||
|
||
```typescript
|
||
export class ICCoderAuthenticationProvider
|
||
implements vscode.AuthenticationProvider
|
||
{
|
||
private _onDidChangeSessions =
|
||
new vscode.EventEmitter<vscode.AuthenticationProviderAuthenticationSessionsChangeEvent>();
|
||
public readonly onDidChangeSessions = this._onDidChangeSessions.event;
|
||
|
||
private _sessions: vscode.AuthenticationSession[] = [];
|
||
}
|
||
```
|
||
|
||
**关键点：**
|
||
|
||
- 实现 `vscode.AuthenticationProvider` 接口
|
||
- 使用 `EventEmitter` 通知会话变化
|
||
- 在内存中维护会话列表
|
||
|
||
#### 1.2 核心方法
|
||
|
||
##### getSessions() - 获取会话列表
|
||
|
||
```typescript
|
||
async getSessions(scopes?: readonly string[]): Promise<readonly vscode.AuthenticationSession[]> {
|
||
return this._sessions;
|
||
}
|
||
```
|
||
|
||
##### createSession() - 创建会话（登录）
|
||
|
||
```typescript
|
||
async createSession(scopes: readonly string[]): Promise<vscode.AuthenticationSession> {
|
||
const token = await this.login();
|
||
|
||
const session: vscode.AuthenticationSession = {
|
||
id: this.generateSessionId(),
|
||
accessToken: token,
|
||
account: {
|
||
id: "iccoder-user",
|
||
label: "IC Coder 用户",
|
||
},
|
||
scopes: [...scopes],
|
||
};
|
||
|
||
this._sessions.push(session);
|
||
await this.saveSessions();
|
||
|
||
this._onDidChangeSessions.fire({
|
||
added: [session],
|
||
removed: [],
|
||
changed: [],
|
||
});
|
||
|
||
return session;
|
||
}
|
||
```
|
||
|
||
**关键点：**
|
||
|
||
- 调用 `login()` 方法获取 token
|
||
- 创建 `AuthenticationSession` 对象
|
||
- 保存到 `globalState`
|
||
- 触发 `onDidChangeSessions` 事件通知 VSCode
|
||
|
||
##### removeSession() - 删除会话（登出）
|
||
|
||
```typescript
|
||
async removeSession(sessionId: string): Promise<void> {
|
||
const sessionIndex = this._sessions.findIndex((s) => s.id === sessionId);
|
||
if (sessionIndex > -1) {
|
||
const session = this._sessions[sessionIndex];
|
||
this._sessions.splice(sessionIndex, 1);
|
||
await this.saveSessions();
|
||
|
||
this._onDidChangeSessions.fire({
|
||
added: [],
|
||
removed: [session],
|
||
changed: [],
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 本地 HTTP 服务器实现
|
||
|
||
#### 2.1 动态端口分配
|
||
|
||
```typescript
|
||
server.listen(0, () => {
|
||
const address = server.address();
|
||
const port = typeof address === "object" && address ? address.port : 3000;
|
||
resolve({ server, port });
|
||
});
|
||
```
|
||
|
||
**关键点：**
|
||
|
||
- 使用端口 `0` 让系统自动分配可用端口
|
||
- 避免端口冲突问题
|
||
- 支持多个用户同时使用
|
||
|
||
#### 2.2 回调处理
|
||
|
||
```typescript
|
||
if (url.pathname === "/callback") {
|
||
const token = url.searchParams.get("token");
|
||
|
||
if (token) {
|
||
// 返回成功页面
|
||
res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
|
||
res.end(this.getSuccessPage(iconBase64));
|
||
|
||
// 关闭服务器
|
||
server.close();
|
||
|
||
// 返回 token
|
||
if ((server as any)._loginResolve) {
|
||
(server as any)._loginResolve(token);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. package.json 配置
|
||
|
||
#### 3.1 注册 Authentication Provider
|
||
|
||
```json
|
||
{
|
||
"contributes": {
|
||
"authentication": [
|
||
{
|
||
"id": "iccoder",
|
||
"label": "IC Coder"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**关键点：**
|
||
|
||
- `id` 必须与代码中使用的 ID 一致
|
||
- `label` 会显示在 VSCode 账户菜单中
|
||
|
||
#### 3.2 注册命令
|
||
|
||
```json
|
||
{
|
||
"contributes": {
|
||
"commands": [
|
||
{
|
||
"command": "ic-coder.login",
|
||
"title": "IC Coder: 登录账户",
|
||
"category": "IC Coder"
|
||
},
|
||
{
|
||
"command": "ic-coder.logout",
|
||
"title": "IC Coder: 退出登录",
|
||
"category": "IC Coder"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. extension.ts 注册
|
||
|
||
#### 4.1 注册 Authentication Provider
|
||
|
||
```typescript
|
||
export function activate(context: vscode.ExtensionContext) {
|
||
// 注册 Authentication Provider
|
||
const authProvider = new ICCoderAuthenticationProvider(context);
|
||
context.subscriptions.push(
|
||
vscode.authentication.registerAuthenticationProvider(
|
||
"iccoder",
|
||
"IC Coder",
|
||
authProvider
|
||
)
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 4.2 登录命令
|
||
|
||
```typescript
|
||
const loginCommand = vscode.commands.registerCommand(
|
||
"ic-coder.login",
|
||
async () => {
|
||
try {
|
||
await vscode.authentication.getSession("iccoder", [], {
|
||
createIfNone: true,
|
||
});
|
||
} catch (error) {
|
||
vscode.window.showErrorMessage(`登录失败: ${error}`);
|
||
}
|
||
}
|
||
);
|
||
```
|
||
|
||
**关键点：**
|
||
|
||
- `createIfNone: true` 会在没有会话时自动调用 `createSession()`
|
||
- VSCode 会自动处理 UI 交互
|
||
|
||
#### 4.3 登出命令
|
||
|
||
```typescript
|
||
const logoutCommand = vscode.commands.registerCommand(
|
||
"ic-coder.logout",
|
||
async () => {
|
||
try {
|
||
const session = await vscode.authentication.getSession("iccoder", [], {
|
||
createIfNone: false,
|
||
});
|
||
if (session) {
|
||
await vscode.authentication.getSession("iccoder", [], {
|
||
clearSessionPreference: true,
|
||
forceNewSession: true,
|
||
});
|
||
vscode.window.showInformationMessage("已退出登录");
|
||
}
|
||
} catch (error) {
|
||
vscode.window.showInformationMessage("当前未登录");
|
||
}
|
||
}
|
||
);
|
||
```
|
||
|
||
### 5. ICViewProvider 集成
|
||
|
||
#### 5.1 检查登录状态
|
||
|
||
```typescript
|
||
private async checkLoginStatus(): Promise<boolean> {
|
||
try {
|
||
const session = await vscode.authentication.getSession("iccoder", [], { createIfNone: false });
|
||
return !!session;
|
||
} catch (error) {
|
||
return false;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5.2 根据登录状态显示不同按钮
|
||
|
||
```typescript
|
||
resolveWebviewView(webviewView: vscode.WebviewView) {
|
||
this.checkLoginStatus().then((isLoggedIn) => {
|
||
webviewView.webview.html = this.getWebviewContent(
|
||
webviewView.webview,
|
||
isLoggedIn
|
||
);
|
||
});
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
${isLoggedIn
|
||
? '<button class="btn" onclick="openChat()">开始创作</button>'
|
||
: '<button class="btn" onclick="login()">登录账户</button>'
|
||
}
|
||
```
|
||
|
||
### 6. 网站前端配置
|
||
|
||
#### 6.1 检测插件登录请求
|
||
|
||
```javascript
|
||
// 在登录页面检测 redirect_uri 参数
|
||
const urlParams = new URLSearchParams(window.location.search);
|
||
const redirectUri = urlParams.get("redirect_uri");
|
||
|
||
if (redirectUri) {
|
||
// 保存回调地址
|
||
localStorage.setItem("plugin_redirect_uri", redirectUri);
|
||
}
|
||
```
|
||
|
||
#### 6.2 登录成功后重定向
|
||
|
||
```javascript
|
||
// 用户登录成功，拿到 token
|
||
const token = response.data.token;
|
||
|
||
// 检查是否需要重定向回插件
|
||
const redirectUri = localStorage.getItem("plugin_redirect_uri");
|
||
|
||
if (redirectUri) {
|
||
// 重定向回插件，带上 token
|
||
window.location.href = `${redirectUri}?token=${token}`;
|
||
localStorage.removeItem("plugin_redirect_uri");
|
||
} else {
|
||
// 正常登录流程
|
||
router.push("/dashboard");
|
||
}
|
||
```
|
||
|
||
## 关键技术点
|
||
|
||
### 1. 动态端口分配
|
||
|
||
**问题：** 固定端口可能被占用，导致登录失败
|
||
|
||
**解决方案：** 使用端口 `0` 让系统自动分配可用端口
|
||
|
||
```typescript
|
||
server.listen(0, () => {
|
||
const address = server.address();
|
||
const port = typeof address === "object" && address ? address.port : 3000;
|
||
});
|
||
```
|
||
|
||
### 2. Promise 异步等待
|
||
|
||
**问题：** 需要等待浏览器登录完成后才能继续
|
||
|
||
**解决方案：** 使用 Promise 包装回调逻辑
|
||
|
||
```typescript
|
||
return new Promise((resolve, reject) => {
|
||
(server as any)._loginResolve = resolve;
|
||
(server as any)._loginReject = reject;
|
||
});
|
||
```
|
||
|
||
### 3. 会话持久化
|
||
|
||
**问题：** 重启 VSCode 后需要重新登录
|
||
|
||
**解决方案：** 使用 `globalState` 保存会话
|
||
|
||
```typescript
|
||
await this.context.globalState.update("icCoderSessions", this._sessions);
|
||
```
|
||
|
||
### 4. 事件通知机制
|
||
|
||
**问题：** VSCode 需要知道会话状态变化
|
||
|
||
**解决方案：** 使用 `EventEmitter` 触发事件
|
||
|
||
```typescript
|
||
this._onDidChangeSessions.fire({
|
||
added: [session],
|
||
removed: [],
|
||
changed: [],
|
||
});
|
||
```
|
||
|
||
## 用户体验
|
||
|
||
### 登录流程
|
||
|
||
1. 用户点击侧边栏"登录账户"按钮
|
||
2. 浏览器自动打开登录页面
|
||
3. 用户在网站完成登录
|
||
4. 浏览器自动跳转到成功页面
|
||
5. VSCode 左下角显示"IC Coder 用户"
|
||
6. 侧边栏按钮变为"开始创作"
|
||
|
||
### 登出流程
|
||
|
||
1. 点击 VSCode 左下角账户图标
|
||
2. 选择"IC Coder"账户
|
||
3. 点击"退出"按钮
|
||
4. 或使用命令 `IC Coder: 退出登录`
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 为什么不直接使用 globalState 存储 token？
|
||
|
||
**A:** 使用 VSCode Authentication API 的优势：
|
||
|
||
- ✅ 统一的用户体验（左下角账户区域）
|
||
- ✅ VSCode 自动管理会话生命周期
|
||
- ✅ 支持多账户切换
|
||
- ✅ 更好的安全性（VSCode 负责加密存储）
|
||
|
||
### Q2: 如何处理 token 过期？
|
||
|
||
**A:** 可以在 API 请求失败时：
|
||
|
||
1. 检测 401 错误
|
||
2. 调用 `removeSession()` 清除过期会话
|
||
3. 提示用户重新登录
|
||
|
||
### Q3: 如何支持多个账户？
|
||
|
||
**A:** 修改 `account` 对象：
|
||
|
||
```typescript
|
||
account: {
|
||
id: userInfo.id,
|
||
label: userInfo.username,
|
||
}
|
||
```
|
||
|
||
### Q4: 登录页面如何获取用户信息？
|
||
|
||
**A:** 可以在登录成功后，通过 API 获取用户信息：
|
||
|
||
```typescript
|
||
const userInfo = await fetch("https://api.iccoder.com/user/info", {
|
||
headers: { Authorization: `Bearer ${token}` },
|
||
});
|
||
|
||
const session: vscode.AuthenticationSession = {
|
||
account: {
|
||
id: userInfo.id,
|
||
label: userInfo.username,
|
||
},
|
||
// ...
|
||
};
|
||
```
|
||
|
||
## 安全考虑
|
||
|
||
### 1. Token 存储
|
||
|
||
- ✅ 使用 VSCode `globalState` 加密存储
|
||
- ✅ 不在代码中硬编码敏感信息
|
||
- ✅ Token 仅在内存和加密存储中传递
|
||
|
||
### 2. 本地服务器
|
||
|
||
- ✅ 仅监听 `localhost`，不暴露到外网
|
||
- ✅ 使用动态端口，避免固定端口被劫持
|
||
- ✅ 接收到 token 后立即关闭服务器
|
||
- ✅ 设置 5 分钟超时，防止服务器长期运行
|
||
|
||
### 3. HTTPS 考虑
|
||
|
||
**当前实现：** 使用 HTTP 本地回调
|
||
|
||
**生产环境建议：**
|
||
|
||
- 网站使用 HTTPS
|
||
- 本地回调使用 HTTP（localhost 不受浏览器限制）
|
||
- 或使用 `vscode://` 协议（需要网站支持）
|
||
|
||
## 测试指南
|
||
|
||
### 1. 本地测试
|
||
|
||
```bash
|
||
# 启动调试模式
|
||
按 F5
|
||
|
||
# 测试登录
|
||
1. 打开侧边栏
|
||
2. 点击"登录账户"
|
||
3. 在浏览器完成登录
|
||
4. 检查左下角是否显示账户
|
||
|
||
# 测试登出
|
||
1. 点击左下角账户
|
||
2. 选择"IC Coder"
|
||
3. 点击"退出"
|
||
```
|
||
|
||
### 2. 调试技巧
|
||
|
||
```typescript
|
||
// 在 ICCoderAuthenticationProvider 中添加日志
|
||
console.log("🔐 创建会话:", session);
|
||
console.log("🔑 Token:", token);
|
||
|
||
// 在 ICViewProvider 中添加日志
|
||
console.log("🔍 登录状态:", isLoggedIn);
|
||
```
|
||
|
||
### 3. 常见错误排查
|
||
|
||
| 错误 | 原因 | 解决方案 |
|
||
| ------------------------------- | --------------- | ---------------------------------- |
|
||
| `getSessions is not a function` | VSCode 版本过低 | 升级到 1.63.0+ |
|
||
| 端口被占用 | 固定端口冲突 | 使用动态端口（已实现） |
|
||
| 登录后未显示账户 | 未触发事件 | 检查 `_onDidChangeSessions.fire()` |
|
||
| 重启后需要重新登录 | 未保存会话 | 检查 `saveSessions()` 调用 |
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
ic-coder/
|
||
├── src/
|
||
│ ├── services/
|
||
│ │ └── icCoderAuthProvider.ts # Authentication Provider 实现
|
||
│ ├── views/
|
||
│ │ └── ICViewProvider.ts # 侧边栏视图（集成登录状态）
|
||
│ └── extension.ts # 注册 Provider 和命令
|
||
├── package.json # 配置 authentication 和 commands
|
||
└── docs/
|
||
└── authentication-implementation.md # 本文档
|
||
```
|
||
|
||
## 参考资料
|
||
|
||
- [VSCode Authentication API](https://code.visualstudio.com/api/references/vscode-api#authentication)
|
||
- [Authentication Provider Sample](https://github.com/microsoft/vscode-extension-samples/tree/main/authentication-sample)
|
||
- [VSCode Extension Guidelines](https://code.visualstudio.com/api/references/extension-guidelines)
|
||
|
||
## 总结
|
||
|
||
本实现通过以下步骤完成了 VSCode Authentication API 的集成：
|
||
|
||
1. ✅ 创建 `ICCoderAuthenticationProvider` 类实现认证逻辑
|
||
2. ✅ 在 `package.json` 中注册 authentication provider
|
||
3. ✅ 在 `extension.ts` 中注册 provider 和命令
|
||
4. ✅ 实现本地 HTTP 服务器处理登录回调
|
||
5. ✅ 使用动态端口避免冲突
|
||
6. ✅ 集成到侧边栏视图，根据登录状态显示不同按钮
|
||
7. ✅ 配置网站前端支持插件登录重定向
|
||
|
||
**最终效果：**
|
||
|
||
- 用户登录后，VSCode 左下角显示"IC Coder 用户"
|
||
- 侧边栏根据登录状态显示"登录账户"或"开始创作"按钮
|
||
- 支持通过账户菜单或命令进行登录/登出操作
|
||
|
||
---
|
||
|
||
**文档版本：** 1.0
|
||
**最后更新：** 2025-12-29
|
||
**作者：** Roe-xin
|