a
This commit is contained in:
@@ -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` 单文件实现全部功能。
|
||||
@@ -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 接入不改变此现状;后续可考虑升级为后端存储 |
|
||||
Reference in New Issue
Block a user