g82tt
68be41e7a2
# 项目概述 个人浏览器首页导航应用，支持书签分类管理、搜索引擎快捷搜索、 必应每日壁纸轮播、前后端分离部署，适配 1Panel 服务器（Docker 模式）。 # 技术栈 - 前端：Vue 3 + TypeScript + Vite + Pinia + Capacitor（Android 打包） - 后端：.NET 8 + SqlSugar（多数据库） + SQLite/MySQL + Swashbuckle - 部署：1Panel 应用商店自定义应用（Docker Compose 模式） # 项目结构 - backend/ .NET 8 API 后端（8 个 Controller + 15 个 Service） - frontend/ Vue 3 前端（19 个组件 + 9 个 API 模块 + 5 个 Store） - docker/ Docker 部署文件（后端镜像 + Nginx 反代） - docs/ 部署手册（1Panel 实战版） - scripts/ E2E 测试脚本 # 已实现功能 - 书签管理：增删改查 + 树形分类 + 拖拽排序 + 主色自适应 - 搜索引擎：8 个内置引擎 + 自定义引擎 + favicon 自动抓取 - 必应壁纸：每日轮播 + 多分辨率自动选择 + 1.6MP 质量优先 - 全局设置：主题/行为/数据/工具 4 分类 + 跨设备同步 - 文件上传：图标/书签/通用（容器持久化 + 跨域 URL 拼接） - 同步：基于变更日志的设备间数据同步 - 跨域部署：前后端分离 + runtime config.json 无需重新编译 # 进度记录 - 已完成 P0~P52 共 53 个开发节点（详细见 说明文档.md） - 当前版本：v1.0 部署就绪 # 部署文档 - README.md：项目说明 + 快速开始 - 说明文档.md：完整开发进度（中文） - docs/DEPLOY.md：1Panel 部署手册（Docker 模式）
169 lines
5.5 KiB
Markdown
169 lines
5.5 KiB
Markdown
# MyHomePage · 浏览器首页
|
||
|
||
> 跨端可用的浏览器首页 / 起始页：PC、平板、手机浏览器 + Android APP 共享同一份数据，实时同步。
|
||
|
||
|
||
|
||
## 功能特性
|
||
|
||
- 二级分类导航（常用工具 > 搜索引擎 / AI 工具 / 开发工具）
|
||
- 链接收藏管理：增删改、图标、简介
|
||
- 搜索引擎管理：增删改、默认引擎切换
|
||
- 设置面板：主题模式（暗/亮/跟随系统）、主色调、背景图（6 套预设 + 自定义上传）
|
||
- PC、平板、手机浏览器自适应
|
||
- PC、平板、手机、Android APP 四端数据实时同步
|
||
- 文件上传（链接图标 / 自定义背景图），落地路径可配置
|
||
- 后端支持 MySQL / SQLite，通过 `appsettings.json` 一键切换
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 选型 |
|
||
|----|------|
|
||
| 前端 | Vue 3 + TypeScript + Vite + Pinia + Vue Router |
|
||
| UI | 自研组件（玻璃拟态设计 token），图标 lucide-vue-next |
|
||
| APP 壳 | Capacitor 6（共享前端代码） |
|
||
| 后端 | .NET 8 + ASP.NET Core Web API + C# |
|
||
| ORM | SqlSugar（多数据库自动切换） |
|
||
| 数据库 | MySQL 8 / SQLite |
|
||
| 部署 | Docker Compose |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
MyHomePage/
|
||
├── frontend/ # Vue 3 前端
|
||
│ ├── src/
|
||
│ │ ├── api/ # axios 封装
|
||
│ │ ├── components/ # 通用组件 + 业务组件
|
||
│ │ ├── views/ # HomeView / SettingsView
|
||
│ │ ├── stores/ # Pinia stores
|
||
│ │ ├── router/ # 路由
|
||
│ │ ├── styles/ # tokens.css + global.css
|
||
│ │ ├── types/ # TypeScript 类型
|
||
│ │ └── utils/ # icon / toast 工具
|
||
│ ├── capacitor.config.ts # Capacitor 配置
|
||
│ ├── ANDROID.md # 打包 Android 指引
|
||
│ ├── package.json
|
||
│ └── vite.config.ts
|
||
├── backend/ # .NET 8 Web API
|
||
│ ├── Controllers/ # 6 个 REST 控制器
|
||
│ ├── Services/ # 业务服务
|
||
│ ├── Models/ # Entities + Dtos
|
||
│ ├── Repositories/ # BaseRepository
|
||
│ ├── Common/ # ApiResponse + 异常中间件
|
||
│ ├── Infrastructure/ # SqlSugarContext + 配置
|
||
│ ├── Uploads/ # 上传文件目录
|
||
│ ├── MyHomePage.Api.csproj
|
||
│ ├── Program.cs
|
||
│ └── appsettings.json
|
||
├── docker/ # Docker 部署资源
|
||
│ ├── backend.Dockerfile
|
||
│ ├── nginx.conf
|
||
│ └── README.md
|
||
├── docker-compose.yml
|
||
└── browser-homepage/ # 设计稿（已存在）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 启动后端
|
||
|
||
```bash
|
||
cd backend
|
||
dotnet restore
|
||
dotnet run
|
||
# 默认监听 http://localhost:5080
|
||
# Swagger UI: http://localhost:5080/swagger
|
||
```
|
||
|
||
第一次启动会自动建表（CodeFirst）并写入种子数据（常用工具 + AI 工具 + 开发工具 3 个分类 + 6 个链接 + 3 个搜索引擎）。
|
||
|
||
### 2. 切换数据库
|
||
|
||
默认 SQLite（`myhomepage.db`）。如需 MySQL：
|
||
|
||
编辑 `backend/appsettings.json`：
|
||
|
||
```json
|
||
{
|
||
"Database": {
|
||
"Provider": "MySql",
|
||
"ConnectionString": "Server=localhost;Port=3306;Database=myhomepage;Uid=root;Pwd=yourpw;CharSet=utf8mb4;"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 启动前端
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
# 默认监听 http://localhost:5173
|
||
```
|
||
|
||
Vite 已配 proxy：`/api` → `http://localhost:5080`。
|
||
|
||
### 4. 浏览器访问
|
||
|
||
打开 http://localhost:5173
|
||
|
||
## 打包 Android APP
|
||
|
||
见 [frontend/ANDROID.md](file:///d:/Code/MyHomePage/frontend/ANDROID.md)
|
||
|
||
## Docker 一键部署
|
||
|
||
见 [docker/README.md](file:///d:/Code/MyHomePage/docker/README.md)
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
# 访问 http://localhost:8080
|
||
```
|
||
|
||
## API 总览
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET / POST / PUT / DELETE | `/api/categories` | 分类 CRUD（支持二级树） |
|
||
| GET / POST / PUT / DELETE | `/api/bookmarks` | 链接 CRUD，可按 `?categoryId=` 过滤 |
|
||
| GET / POST / PUT / DELETE | `/api/search-engines` | 搜索引擎 CRUD |
|
||
| PUT | `/api/search-engines/{id}/default` | 设为默认（自动取消其他） |
|
||
| GET / PUT | `/api/settings` | 用户设置读写 |
|
||
| POST | `/api/upload` | 单文件上传，返回 `{ url, path, ... }` |
|
||
| GET | `/api/sync/changes?since={ISO8601}` | 增量同步，返回 `{ changes, snapshot, serverTime }` |
|
||
| GET | `/health` | 健康检查 |
|
||
| GET | `/swagger` | OpenAPI 文档 |
|
||
|
||
所有接口统一响应格式：
|
||
```json
|
||
{ "code": 0, "message": "ok", "data": { ... }, "timestamp": 1783158000000 }
|
||
```
|
||
|
||
`code !== 0` 表示业务错误，`code === 0` 表示成功。
|
||
|
||
## 上传路径配置
|
||
|
||
```json
|
||
{
|
||
"Upload": {
|
||
"Path": "Uploads", // 相对 ContentRoot；填绝对路径也支持
|
||
"BaseUrl": "/uploads", // 前端拼接前缀
|
||
"MaxSizeBytes": 10485760 // 10MB
|
||
}
|
||
}
|
||
```
|
||
|
||
通过环境变量覆盖：`Upload__Path=/data/uploads`、`Upload__BaseUrl=https://cdn.example.com/uploads`。
|
||
|
||
## 开发约定
|
||
|
||
- 严格按 [说明文档.md](file:///d:/Code/MyHomePage/说明文档.md) 中的 TODO 推进
|
||
- 每次完成一个任务立即更新「说明文档」中的进度记录
|
||
- 函数级注释（功能 / 参数 / 返回值），便于 AI 理解
|
||
- API 错误码用 4xx 表示业务校验失败，5xx 表示系统错误
|
||
|
||
## License
|
||
|
||
MIT
|