MyHomepage/README.md

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. 启动后端

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：

{
  "Database": {
    "Provider": "MySql",
    "ConnectionString": "Server=localhost;Port=3306;Database=myhomepage;Uid=root;Pwd=yourpw;CharSet=utf8mb4;"
  }
}

3. 启动前端

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

Docker 一键部署

见 docker/README.md

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 文档

所有接口统一响应格式：

{ "code": 0, "message": "ok", "data": { ... }, "timestamp": 1783158000000 }

code !== 0 表示业务错误，code === 0 表示成功。

上传路径配置

{
  "Upload": {
    "Path": "Uploads",        // 相对 ContentRoot；填绝对路径也支持
    "BaseUrl": "/uploads",    // 前端拼接前缀
    "MaxSizeBytes": 10485760  // 10MB
  }
}

通过环境变量覆盖：Upload__Path=/data/uploads、Upload__BaseUrl=https://cdn.example.com/uploads。

开发约定

• 严格按 说明文档.md 中的 TODO 推进
• 每次完成一个任务立即更新「说明文档」中的进度记录
• 函数级注释（功能 / 参数 / 返回值），便于 AI 理解
• API 错误码用 4xx 表示业务校验失败，5xx 表示系统错误

License

MIT