This commit is contained in:
Ubuntu
2026-07-03 16:58:28 +08:00
commit 32b43f85bd
6240 changed files with 1987678 additions and 0 deletions
+142
View File
@@ -0,0 +1,142 @@
# Nanocode Portal — 设计文档
## 项目概述
在 `/home/ubuntu/nanocode/www` 下实现一个纯前端 SPA 导航门户,作为 nginx 80 端口的首页,聚合所有个人项目的入口链接。
---
## 技术方案
| 项 | 决策 |
|---|---|
| 架构 | 纯前端 SPA,单 HTML 文件 + 内嵌 CSS/JS |
| 数据存储 | `localStorage`(无后端) |
| 登录凭据 | 硬编码 `admin` / `abcd1234`,localStorage 标记登录态 |
| 密码修改 | 老密码验证通过后,更新硬编码逻辑(localStorage 覆盖) |
| 图标生成 | 根据链接名称的首字母/哈希生成固定颜色 + 大写字母 |
| 布局 | CSS Grid,PC 端 4 列,响应式到移动端 1 列 |
| 3D 倾斜 | CSS `transform: perspective + rotateX/Y`,基于鼠标位置计算 |
---
## 数据模型
```json
{
"links": [
{
"id": "uuid",
"name": "个人博客",
"url": "http://129.211.173.87:8888",
"description": "基于 Next.js 的个人技术博客"
}
],
"auth": {
"token": "random-string",
"passwordHash": "sha256-of-current-password"
}
}
```
- `links` 数组存储所有导航卡片
- `auth` 对象存储登录态和密码哈希(SHA-256)
---
## 默认预设链接(根据现有项目)
| 名称 | 链接 | 描述 |
|---|---|---|
| 个人博客 | `:8888` | Next.js 技术博客 |
| 相册查看器 | `:8892` | 图片相册浏览 |
| 快乐游戏 | `:8895` | Flask 小游戏集合 |
| 网游引擎 | `:8900` | 网游引擎服务 |
| 有声书播放器 | `:8899` | 有声书在线播放 |
| WanAndroid | `:8880` | Material Design Web |
| FumaMX CRM | `:10000` | CRM 管理系统 |
| AI 聊天服务 | `:8890` | AI 对话服务 |
| 新媒体平台 | `:18888` | CMS 内容管理系统 |
| 微信小程序桥接 | `:5000` | 微信-Nanobot 桥接 |
> 注:具体端口以运行时 systemd 服务实际监听为准。
---
## 交互设计
### 1. 未登录状态
- 页面顶部右侧:「登录」按钮
- 点击弹出模态框:账号 / 密码输入框
- 验证失败提示红色错误信息
### 2. 登录成功状态
- 页面顶部右侧:「修改密码」+「添加链接」两个按钮
### 3. 修改密码
- 弹窗:老密码 / 新密码 / 确认新密码
- 老密码验证通过后更新 localStorage 中的密码哈希
### 4. 添加链接
- 弹窗:名称(文本)/ 链接(URL)/ 介绍(文本)
- 提交后追加到 links 数组,重新渲染
### 5. 卡片交互
- **常态**:白底卡片,大圆角(`border-radius: 20px`),阴影(`box-shadow`),左侧彩色圆形图标(首字母),右侧上下两行文字
- **Hover**:
- 卡片 3D 倾斜(基于鼠标在卡片内的相对位置计算 `rotateX` / `rotateY`)
- 右上角浮现「×」关闭按钮
- **点击关闭按钮**:确认后从数组删除,localStorage 同步更新
- **点击卡片主体**:`window.open(url, '_blank')`
---
## 3D 倾斜效果实现思路
```
鼠标在卡片内的相对位置 → 映射到 [-1, 1] → 乘以最大旋转角度(如 ±10deg)
transform: perspective(1000px) rotateX(ry * -1) rotateY(rx)
```
- `rx` = (mouseX / cardWidth - 0.5) * 2
- `ry` = (mouseY / cardHeight - 0.5) * 2
鼠标移出时:平滑过渡(`transition: transform 0.3s ease`)复原到 `rotateX(0) rotateY(0)`。
---
## 样式规范
- 背景:浅灰渐变或纯色 `#f5f7fa`
- 顶部导航栏:白色,底部细阴影,高度 60px
- 卡片:白色,圆角 20px,padding 24px,gap 24px
- Grid:`grid-template-columns: repeat(4, 1fr)`,PC 端;`repeat(2, 1fr)` 平板;`1fr` 手机
- 图标:圆形 64px,背景色根据名称哈希生成(HSL 色环),文字白色大写首字母
- 关闭按钮:红色圆形,直径 24px,卡片 hover 时 `opacity: 0 → 1`
---
## 文件结构
```
/home/ubuntu/nanocode/www/
├── index.html # 单文件 SPA(HTML + CSS + JS)
└── docs/
└── DESIGN.md # 本文档
```
---
## 待确认问题
1. **图标生成方式**:当前设计是根据名称首字母生成固定彩色字母图标。是否需要支持用户上传自定义图标?还是保持自动生成即可?
2. **删除确认**:点击关闭按钮删除时,是否需要二次确认弹窗("确定删除此链接?"),还是直接删除?
3. **默认链接**:上方列出的预设链接是否符合预期?是否有遗漏或不需要的项目?
4. **公网 IP**:链接中硬编码 `129.211.173.87` 是否合适,还是希望用相对路径或域名?
5. **排序**:新增链接是追加到末尾,还是可以拖拽排序?
---
## 下一步
确认上述问题后,直接编写 `/home/ubuntu/nanocode/www/index.html` 单文件实现全部功能。
+236
View File
@@ -0,0 +1,236 @@
# WWW 门户 SSO 接入方案
## 1. 现状分析
### 1.1 www 项目当前架构
- **纯前端 SPA**,单文件 `index.html`,由 nginx 80 端口静态托管
- **无后端**,所有逻辑(认证、数据增删)均在客户端 JS 完成
- 当前认证方式:
- 硬编码账号 `admin / abcd1234`
- 密码经 SHA-256 哈希后存入 `localStorage`
- 登录态由 `localStorage.auth` 标记
- 已有功能:登录、修改密码、添加链接、删除链接
### 1.2 SSO 中心(usercenter)现状
- FastAPI 服务,运行在 `:9000`
- Cookie 配置:`Domain=129.211.173.87`,`SameSite=Lax`,`HttpOnly=True`
- 提供的 API:
- `GET /` — 登录页(支持 `?redirect=` 参数)
- `POST /api/login` — 登录,种 Cookie
- `POST /api/logout` — 登出,清 Cookie
- `GET /api/userinfo` — 返回 `{"username":"admin"}`(需 Cookie 认证)
- `POST /api/change-password` — 修改密码
- CORS 当前仅允许 `:8888`、`:8889`、`:9000`
### 1.3 关键差异
| 项目 | personal-blog | www |
|------|--------------|-----|
| 后端 | FastAPI (`:8889`) | **无后端** |
| 认证方式 | Bearer Token + SSO Cookie 双模式 | 纯 localStorage |
| 接入难度 | 中(需改后端认证逻辑) | 低(仅改前端 JS) |
## 2. 接入方案
### 2.1 核心思路
www 项目没有后端,无法做服务端 Cookie 验签。采用 **前端 API 探测** 方案:
- 页面加载时,JS 跨域调用 SSO 中心 `/api/userinfo`(携带 Cookie)
- 返回 200 → 已登录 → 展示管理功能
- 返回 401 → 未登录 → 展示 SSO 登录按钮
- 登录按钮跳转 SSO 中心,登录后 redirect 回门户
### 2.2 认证流程
```
用户访问 http://129.211.173.87/ (门户首页)
│
▼
JS 调用 SSO /api/userinfo(credentials: 'include')
│
┌────┴────┐
│ │
200 OK 401
│ │
▼ ▼
展示 展示
管理UI 「SSO 登录」按钮
│
▼ 点击
跳转 http://129.211.173.87:9000/?redirect=http://129.211.173.87/
│
▼ SSO 登录成功
浏览器种 Cookie → redirect 回门户
│
▼
页面重新加载 → JS 再调 /api/userinfo → 200 → 展示管理UI
```
### 2.3 跨域 Cookie 可行性分析
| 条件 | 值 | 结论 |
|------|---|------|
| SSO Cookie Domain | `129.211.173.87` | ✅ www (`:80`) 同 IP,浏览器会带 Cookie |
| SameSite | `Lax` | ✅ 顶级导航跳转(redirect)带 Cookie;跨域 fetch 需 `credentials: 'include'` |
| CORS `allow_credentials` | `True` | ✅ SSO 中心已开启 |
| CORS `allow_origins` | 需追加 `http://129.211.173.87` | ⚠️ **需修改** |
> **注意**:`SameSite=Lax` 下,跨域 `fetch` + `credentials: 'include'` 在部分浏览器版本中行为不一致。但当前场景中,用户从 SSO 中心 redirect 回门户时是**顶级导航**,Cookie 一定会带上。fetch 探测仅用于页面加载后的状态检查,即使偶尔探测失败,刷新页面即可恢复。
## 3. 具体改动
### 3.1 SSO 中心(usercenter)— 1 处改动
**文件**:`/home/ubuntu/nanocode/usercenter/app.py`
```python
# CORS allow_origins 新增一行
allow_origins=[
"http://129.211.173.87:8888",
"http://129.211.173.87:8889",
"http://129.211.173.87:9000",
"http://129.211.173.87", # ← 新增:www 门户(80 端口)
],
```
### 3.2 www 门户 — 1 个文件改动
**文件**:`/home/ubuntu/nanocode/www/index.html`
#### 改动清单
| # | 改动 | 说明 |
|---|------|------|
| 1 | 删除 `hashPass` / `checkPass` / `genId` 等本地认证函数 | 不再需要 |
| 2 | 删除 `localStorage` 中 `auth` 相关的读写 | 不再需要 |
| 3 | `isLoggedIn()` 改为基于 SSO 状态变量 | 异步检测,非同步读 localStorage |
| 4 | 新增 `checkSSOStatus()` | 调用 `http://129.211.173.87:9000/api/userinfo`,`credentials: 'include'` |
| 5 | 页面加载时调用 `checkSSOStatus()` | 替代原 `updateNavbar()` 的同步逻辑 |
| 6 | 登录按钮改为跳转 SSO | `window.location.href = 'http://129.211.173.87:9000/?redirect=...'` |
| 7 | 删除「修改密码」入口 | 密码管理统一到 SSO 中心 |
| 8 | 退出改为调用 SSO `/api/logout` | `fetch('.../api/logout', {method:'POST', credentials:'include'})` |
| 9 | 删除登录弹窗 HTML | 不再需要本地登录表单 |
| 10 | 删除修改密码弹窗 HTML | 不再需要 |
#### 核心代码示意
```javascript
// SSO 配置
const SSO_BASE = 'http://129.211.173.87:9000';
let ssoUser = null; // 当前 SSO 登录用户名
// 检测 SSO 登录状态
async function checkSSOStatus() {
try {
const res = await fetch(`${SSO_BASE}/api/userinfo`, {credentials: 'include'});
if (res.ok) {
const data = await res.json();
ssoUser = data.username;
} else {
ssoUser = null;
}
} catch {
ssoUser = null;
}
updateNavbar();
}
// SSO 登录(跳转)
function ssoLogin() {
const redirect = window.location.origin + window.location.pathname;
window.location.href = `${SSO_BASE}/?redirect=${encodeURIComponent(redirect)}`;
}
// SSO 登出
async function ssoLogout() {
await fetch(`${SSO_BASE}/api/logout`, {method: 'POST', credentials: 'include'});
ssoUser = null;
updateNavbar();
}
// 是否已登录(SSO)
function isLoggedIn() {
return ssoUser !== null;
}
// 页面加载
checkSSOStatus();
renderCards();
```
#### 导航栏 UI 变化
**未登录时**:
- 按钮:「SSO 统一登录」(跳转 SSO 中心)
**已登录时**:
- 显示用户名
- 按钮:「添加链接」「退出」
- 移除「修改密码」(统一在 SSO 用户中心管理)
## 4. 实施步骤
### Step 1:修改 SSO 中心 CORS
```bash
# 编辑 /home/ubuntu/nanocode/usercenter/app.py
# allow_origins 增加 "http://129.211.173.87"
# 重启 usercenter 服务
sudo systemctl restart usercenter
```
### Step 2:修改 www 门户 index.html
```
1. 删除:本地认证相关 JS 函数(hashPass、checkPass、genId、doLogin、doChangePass)
2. 删除:localStorage auth 读写函数(setAuth、clearAuth、getAuth)
3. 删除:登录弹窗 HTML(loginModal)
4. 删除:修改密码弹窗 HTML(passModal)
5. 新增:SSO 状态检测函数 checkSSOStatus()
6. 新增:ssoLogin()、ssoLogout() 函数
7. 修改:isLoggedIn() → 基于 ssoUser 变量
8. 修改:updateNavbar() → 未登录显示「SSO 统一登录」,已登录显示用户名 + 退出
9. 修改:页面初始化 → checkSSOStatus() 替代同步 updateNavbar()
```
### Step 3:验证测试
```bash
# 1. 验证 SSO CORS 配置
curl -s -H "Origin: http://129.211.173.87" \
-H "Cookie: access_token=<valid_token>" \
http://129.211.173.87:9000/api/userinfo
# 2. 浏览器测试
# - 访问 http://129.211.173.87/ → 应显示未登录状态
# - 点击「SSO 统一登录」→ 跳转到 :9000 登录页
# - 输入 admin / abcd1234 → 登录成功 redirect 回门户
# - 门户应显示已登录状态,可添加/删除链接
# - 点击「退出」→ 回到未登录状态
```
### Step 4:清理遗留
```bash
# 清除浏览器 localStorage 中旧的 auth 数据
# (无需手动处理,新版代码不再读取旧 auth key,用户清除浏览器缓存即可)
```
## 5. 不改动的部分
- **链接数据**(`localStorage.links`)— 保持不变,与认证无关
- **卡片渲染/3D 倾斜** — 保持不变
- **nginx 配置** — 保持不变
- **SSO 中心核心逻辑** — 仅改 CORS,不动登录/验签/密码逻辑
- **personal-blog 项目** — 无需改动
## 6. 风险与注意事项
| 风险 | 应对 |
|------|------|
| 跨域 fetch 携带 Cookie 在部分浏览器可能失败 | 顶级导航(SSO redirect 回来)后页面刷新自动带 Cookie,fetch 仅作辅助检测 |
| SSO 中心宕机导致门户无法判断登录态 | `checkSSOStatus()` 捕获异常后按未登录处理,不影响门户浏览;管理功能暂不可用 |
| `localStorage.links` 数据无服务端保护 | 原本就是纯前端存储,SSO 接入不改变此现状;后续可考虑升级为后端存储 |