105 lines
6.0 KiB
Markdown
105 lines
6.0 KiB
Markdown
# Nebula
|
||
|
||
Nebula 是一个用于分发桌面/客户端应用版本的全栈项目，后端使用 Go (Gin + GORM) 暴露应用、版本、资产、更新检查与 JWT 身份验证接口，前端使用 Vue 3 + Vite 构建管理控制台。
|
||
|
||
## 🔍 项目概览
|
||
|
||
- **API 服务** (`cmd/nebula-server` + `internal/`): 提供应用、版本、资产、更新校验、认证等 REST API，并支持本地文件存储。
|
||
- **Web 控制台** (`web/`): Vue 3 + TypeScript + Pinia + Vue Router，负责登录、版本管理等 UI。
|
||
- **文档** (`docs/`): 包含资产接口、JWT、JSON Key、发布 API 以及更新检查规格。
|
||
- **脚本** (`scripts/`): 统一封装 dev/build/start 脚本（.sh/.bat）。
|
||
|
||
```
|
||
.
|
||
├── cmd/nebula-server # API 服务入口
|
||
├── internal/ # 领域服务、API 路由、存储、认证等
|
||
├── web/ # Vue 3 前端应用
|
||
├── docs/ # API 与协议文档
|
||
├── scripts/ # 本地开发与构建脚本
|
||
├── config*.yaml # 运行配置 (默认、dev、prod)
|
||
├── uploads/ # 本地存储文件输出目录
|
||
└── go.mod # Go 依赖定义
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 准备依赖
|
||
|
||
- Go 1.21+（`go.mod` 设定 1.25，使用最新稳定版即可）
|
||
- Node.js 20+ 与 [pnpm](https://pnpm.io/)（前端）
|
||
|
||
### 2. 配置后端
|
||
|
||
1. 复制并调整配置：`cp config.dev.yaml config.yaml`（Windows 可使用 `copy`）。
|
||
2. 启动 API 服务：
|
||
- 开发模式：`go run ./cmd/nebula-server`
|
||
- 生产构建：`go build -o bin/nebula-server ./cmd/nebula-server`
|
||
3. 默认会初始化本地 SQLite 数据库、文件存储与 JWT 认证。
|
||
|
||
### 3. 启动前端
|
||
|
||
```bash
|
||
cd web
|
||
pnpm install
|
||
pnpm dev # 开发热更新
|
||
pnpm build # 生产构建，产物位于 web/dist
|
||
```
|
||
|
||
也可以使用 `scripts/dev.(sh|bat)`、`scripts/build.(sh|bat)`、`scripts/start.(sh|bat)` 进行一键操作。
|
||
|
||
## 📚 文档资源
|
||
|
||
- `docs/ASSET_API.md` – 资产上传/管理接口规格
|
||
- `docs/AUTH_JWT.md` – JWT 身份认证说明
|
||
- `docs/JSON_KEY_FORMAT.md` – JSON Key 结构
|
||
- `docs/RELEASE_API.md` – 发布版本 API
|
||
- `docs/UPDATE_CHECK.md` – 客户端更新检查流程
|
||
|
||
## 📦 功能实现情况
|
||
|
||
### 后端 API 与服务
|
||
|
||
| 模块 | 功能 | 状态 | 说明 |
|
||
|------|------|------|------|
|
||
| 认证 | 管理员/普通用户登录、Refresh、Profile、改密 | ✅ 已落地 | `AuthHandler.Login/RefreshToken/GetProfile/ChangePassword` 已通过 `JWTMiddleware` 保护，并支持配置中的默认管理员。 |
|
||
| 认证 | 自助注册 | 🟡 未启用 | `AuthHandler.Register` 与 `AuthService.Register` 已实现，但 `/api/auth/register` 在路由中被注释以限制注册，`docs/AUTH_JWT.md` 需同步说明。 |
|
||
| 应用 | CRUD | ✅ 已落地 | `AppService` + `AppHandler` 覆盖列表/详情/创建/更新/删除。 |
|
||
| 版本 | CRUD + 最新版本查询 | ✅ 基本可用 | `ReleaseService` 支持按渠道筛选及 `GetLatest`，但 Delete 目前不会清理关联资源（见 TODO #3）。 |
|
||
| 资源 | 列表/详情/外链创建/上传/下载 | ✅ 已落地 | `AssetService` 负责校验和计算、本地存储、下载路径转换。 |
|
||
| 资源 | 数字签名与删除日志 | 🟡 待补完 | 上传时 `Signature` 仍为空，删除文件失败只留下 TODO（见 TODO #1/#2）。 |
|
||
| 更新检查 | `/api/check-update` | ✅ 已落地 | `updater.CheckUpdate` 使用语义化版本比较和校验和返回。 |
|
||
| 存储 | LocalStorage | ✅ 已落地 | file save/delete/url/exists 已实现并在 `main.go` 注入。 |
|
||
| 存储 | OSS / S3 适配器 | ⏳ 预留接口 | `storage.Storage` 提供接口，配置项存在但尚无实现分支。 |
|
||
| 中间件 | AdminMiddleware | ⚠️ 未接入 | 中间件已实现，但目前所有受保护路由仅做 JWT 校验，未强制管理员角色。 |
|
||
|
||
### 前端 Web 控制台
|
||
|
||
| 功能 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| 登录页 | ✅ 可用 | `view/auth/login.vue` 已接入 `api.login` 与 Pinia 存储，并写入 localStorage。 |
|
||
| Token 刷新 | 🟡 未使用 | `api.refreshToken` 定义但尚未在 store/拦截器中调用，实际会在 Access Token 过期后直接失败。 |
|
||
| 仪表盘数据 | 🟡 静态占位 | `view/home/index.vue` 的统计卡片与最近动态均为硬编码示例，尚未调用后端。 |
|
||
| 导航/路由 | ⚠️ 不完整 | 路由仅注册 `/` 与 `/login`，但 `layout/default.vue` 的“应用管理”“系统设置”菜单会指向不存在的路由。 |
|
||
| 应用/版本/资产管理 UI | 🔲 未实现 | 目前没有对应的列表、表单或上传界面，API 只能通过 Postman/curl 使用。 |
|
||
| 注册/忘记密码 UI | 🔲 未实现 | 登录页仅展示提示文字，未提供表单或链接。 |
|
||
|
||
## ✅ 当前 TODO 列表
|
||
|
||
| # | 模块 | 文件 | 待办 | 建议思路 |
|
||
|---|------|------|------|----------|
|
||
| 1 | 资产上传 | `internal/asset/service.go` (行 133) | `Signature` 字段目前为空，需要实现文件签名生成与校验。 | 生成私钥签名或哈希签名存入字段，并在客户端校验；可考虑与 release key 绑定。 |
|
||
| 2 | 资产删除 | `internal/asset/service.go` (行 226) | 删除存储文件失败时仅注释提醒，需要记录日志。 | 注入 logger（`pkg/logger`）并输出错误详情，便于排查存储清理问题。 |
|
||
| 3 | 版本删除 | `internal/release/service.go` (行 137) | 删除 Release 时尚未同步删除关联 Assets。 | 在删除前查询并删除对应资产（含文件），或配置数据库外键级联，确保无孤立文件。 |
|
||
|
||
> 若新增 TODO，请同步更新此表，保持 README 成为 backlog 的单一事实来源。
|
||
|
||
## 🧪 测试与质量
|
||
|
||
- 后端可使用 `go test ./...` 运行单元测试。
|
||
- 前端使用 `pnpm test`（若添加测试工具）或 `pnpm lint` 保持规范。
|
||
|
||
## 🗺️ 后续展望
|
||
|
||
- 为资产签名、删除链路补全 TODO 后，可引入对象存储（S3、OSS 等）与 CI/CD 流水线。
|
||
- 可基于 `docs/UPDATE_CHECK.md` 实现自动更新客户端 SDK。
|