XuJiacheng/Xu_BrowserBookmark
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

提交0.1.0版本

Browse Source 
- 完成了书签的基本功能和插件
This commit is contained in:
徐
2026-01-21 23:09:33 +08:00
parent 3e2d1456eb
commit 1a3bbac9ff
95 changed files with 12431 additions and 12445 deletions
Download Patch File Download Diff File Expand all files Collapse all files

327
README.md
View File

@@ -1,174 +1,153 @@
# BrowserBookmark
内部私域书签管理：Web + 浏览器扩展（MV3）。
## 环境要求
- Node.js 22+
- 包管理器：npm
- Postgres（仅后端直连）
- OpenSpec（全局安装）：`npm install -g @fission-ai/openspec@latest`
## 开发
- 启动后端：`npm run dev:server`
- 启动 Web：`npm run dev:web`
- 启动扩展：`npm run dev:extension`
- 同时启动（server+web）：`npm run dev`
## 规范（Spec-first）
- 规范在 `spec/openapi.yaml`
- 校验：`npm run spec:lint` / `npm run spec:validate`
## 配置
- 复制 `.env.example` 为 `.env` 并填写数据库与密钥。
## 发布（NAS / SSH / x86 Linux）
以下步骤适用于你描述的环境：x86 Linux NAS + SSH 部署，已安装 Node.js 24 与 pm2。
### 0) 本地已执行的命令（在本机开发环境）
- 路径：仓库根目录
- 已执行：
- `npm install`
- `npm run build`
这会生成下列产物：
- Web 构建产物：`apps/web/dist/`
- 扩展构建产物：`apps/extension/dist/`
- 后端为 Node 直接运行源代码（`apps/server/src/`）
### 1) 服务器目录建议（NAS）
建议在 NAS 上建立如下目录结构（可按需调整）：
```
/opt/browser-bookmark/
├── server/ # 后端源码与依赖
├── web/ # Web 静态站点
└── extension/ # 扩展构建产物（用于打包/发布或本地加载）
```
### 2) 通过 SSH 上传文件
以下是需要上传的内容与目标路径：
1. 后端（运行源码）
- 本地：`apps/server/`
- 服务器：`/opt/browser-bookmark/server/`
2. Web 前端（静态产物）
- 本地：`apps/web/dist/`
- 服务器：`/opt/browser-bookmark/web/`
3. 扩展产物（打包或本地加载）
- 本地：`apps/extension/dist/`
- 服务器：`/opt/browser-bookmark/extension/`
4. 部署配置文件
- 本地：`deploy/`
- 服务器：`/opt/browser-bookmark/deploy/`
你可以使用 `scp` 或 `rsync`（示例命令需替换服务器地址与用户名）：
```bash
# 后端源码
rsync -avz ./apps/server/ user@YOUR_NAS:/opt/browser-bookmark/server/
# Web 构建产物
rsync -avz ./apps/web/dist/ user@YOUR_NAS:/opt/browser-bookmark/web/
# 扩展构建产物
rsync -avz ./apps/extension/dist/ user@YOUR_NAS:/opt/browser-bookmark/extension/
# 部署配置
rsync -avz ./deploy/ user@YOUR_NAS:/opt/browser-bookmark/deploy/
```
### 3) 服务器端安装依赖
登录到 NAS：
```bash
ssh user@YOUR_NAS
```
在服务器的后端目录安装依赖：
```bash
cd /opt/browser-bookmark/server
npm install --omit=dev
```
### 4) 配置环境变量
在服务器 `server` 目录准备 `.env`：
```bash
cd /opt/browser-bookmark/server
cp .env.example .env
```
根据你的数据库与密钥填写 `.env`。
### 5) 初始化数据库（首次部署必做）
```bash
cd /opt/browser-bookmark/server
npm run db:migrate
```
### 6) 使用 systemd 启动后端
本仓库已生成 systemd 服务文件：`deploy/systemd/browser-bookmark-server.service`。
将其复制到服务器并启用：
```bash
sudo cp /opt/browser-bookmark/deploy/systemd/browser-bookmark-server.service /etc/systemd/system/browser-bookmark-server.service
sudo systemctl daemon-reload
sudo systemctl enable browser-bookmark-server
sudo systemctl start browser-bookmark-server
```
查看服务状态：
```bash
sudo systemctl status browser-bookmark-server
```
### 7) 配置 Nginx（端口 6666）
本仓库已生成 Nginx 配置文件：`deploy/nginx/mark.cloud-xl.top.conf`。
将其复制到服务器并启用：
```bash
sudo cp /opt/browser-bookmark/deploy/nginx/mark.cloud-xl.top.conf /etc/nginx/conf.d/mark.cloud-xl.top.conf
sudo nginx -t
sudo systemctl reload nginx
```
该配置将 `mark.cloud-xl.top:6666` 指向 `/opt/browser-bookmark/web/`。
### 8) 扩展发布/加载
扩展产物位于服务器：`/opt/browser-bookmark/extension/`。
- 如需本地加载：将该目录下载到你的桌面浏览器，用“加载已解压扩展”指向该目录。
- 如需打包发布到商店：以该目录为基础打包（按平台要求）。
### 9) 验证与排查
- 后端日志：
```bash
sudo journalctl -u browser-bookmark-server -f
```
- Web 是否可访问（浏览器访问你的域名/端口）。
- 扩展是否能正常登录与同步。
### 10) 版本更新流程（建议）
1. 本地执行：`npm install` 与 `npm run build`
2. 重新上传：`apps/server/`、`apps/web/dist/`、`apps/extension/dist/`
3. 服务器端：`npm install --omit=dev`（如依赖变更）
4. 重启服务：`sudo systemctl restart browser-bookmark-server`
# BrowserBookmark
内部私域书签管理：Web + 浏览器扩展（MV3）。
## 环境要求
- Node.js 22+
- 包管理器：npm
- Postgres（仅后端直连）
- OpenSpec（全局安装）：`npm install -g @fission-ai/openspec@latest`
## 开发
- 启动后端：`npm run dev:server`
- 启动 Web：`npm run dev:web`
- 启动扩展：`npm run dev:extension`
- 同时启动（server+web）：`npm run dev`
## 规范（Spec-first）
- 规范在 `spec/openapi.yaml`
- 校验：`npm run spec:lint` / `npm run spec:validate`
## 配置
- 复制 `.env.example` 为 `.env` 并填写数据库与密钥。
## 发布（NAS / SSH / x86 Linux）
本节记录**当前已部署的真实配置**（供 AI 直接执行/更新使用）。
### ✅ 当前部署清单（必须保持一致）
**部署目录**
- 代码根目录：`/home/xxl/Code/bookmark`
**域名与端口**
- 前端 Web：`http://mark.cloud-xl.top:9527`
- 后端 API 代理：`http://mark.cloud-xl.top:9526`（转发到后端 3001）
**后端运行方式**
- systemd：`browser-bookmark-server.service`
- 后端监听端口：`SERVER_PORT=3001`（由 `.env` 提供）
**前端运行方式**
- Docker 容器：`nginx`
- 端口映射：`9527 -> 80`
- Web 根目录（容器内）：`/usr/share/nginx/html`
- 挂载来源：`/home/xxl/Code/bookmark/apps/web/dist`
**API 代理方式**
- Docker 容器：`nginx-api`
- 端口映射：`9526 -> 80`
- 代理目标：`http://host.docker.internal:3001`
- 配置文件：`/home/xxl/Code/bookmark/deploy/nginx/mark.cloud-xl.top.api.conf`
**扩展包**
- 构建输出：`/home/xxl/Code/bookmark/apps/extension/dist`
- 打包文件：`/home/xxl/Code/bookmark/apps/extension/extension-dist.zip`
- 下载地址：`http://mark.cloud-xl.top:9527/extension-dist.zip`
**防火墙放行（iptables）**
- 已放行：`9526`、`9527`
### 1) 初次部署/重建（在服务器执行）
**路径：`/home/xxl/Code/bookmark`**
```bash
npm install
npm run build
```
说明：
- Web 构建产物：`apps/web/dist/`
- 扩展构建产物：`apps/extension/dist/`
- 后端运行仍是 `apps/server/src/`
### 2) 数据库初始化
```bash
cd /home/xxl/Code/bookmark
npm -w apps/server run db:migrate
```
### 3) systemd 启动后端（并开机自启）
```bash
sudo cp /home/xxl/Code/bookmark/deploy/systemd/browser-bookmark-server.service /etc/systemd/system/browser-bookmark-server.service
sudo systemctl daemon-reload
sudo systemctl enable browser-bookmark-server
sudo systemctl start browser-bookmark-server
```
### 4) 前端 Docker Nginx（9527）
```bash
sudo docker stop nginx || true
sudo docker rm nginx || true
sudo docker run -d --name nginx -p 9527:80 \
-v /home/xxl/Code/bookmark/deploy/nginx/mark.cloud-xl.top.conf:/etc/nginx/conf.d/default.conf:ro \
-v /home/xxl/Code/bookmark/apps/web/dist:/usr/share/nginx/html:ro \
nginx:latest
```
### 5) API 代理 Docker Nginx（9526）
```bash
sudo docker stop nginx-api || true
sudo docker rm nginx-api || true
sudo docker run -d --name nginx-api -p 9526:80 \
--add-host=host.docker.internal:host-gateway \
-v /home/xxl/Code/bookmark/deploy/nginx/mark.cloud-xl.top.api.conf:/etc/nginx/conf.d/default.conf:ro \
nginx:latest
```
### 6) 防火墙放行
```bash
sudo iptables -I UG_INPUT 1 -p tcp --dport 9527 -j ACCEPT
sudo iptables -I UG_INPUT 1 -p tcp --dport 9526 -j ACCEPT
```
### 7) 生成并发布扩展包
```bash
cd /home/xxl/Code/bookmark/apps/extension/dist
zip -r ../extension-dist.zip .
cp /home/xxl/Code/bookmark/apps/extension/extension-dist.zip /home/xxl/Code/bookmark/apps/web/dist/extension-dist.zip
```
### 8) 验证清单（服务器内）
```bash
curl -s http://127.0.0.1:9527 | head -n 5
curl -s http://127.0.0.1:9526/health
curl -I http://127.0.0.1:9527/extension-dist.zip
```
### 9) 更新流程（以后改代码时）
> 每次修改后都按以下顺序更新，保证线上一致。
1) **构建**（服务器或本地）
- `npm install`
- `npm run build`
2) **更新 Web 访问后端端口**
- 修改 `apps/web/.env.production` 中的 `VITE_SERVER_BASE_URL`，保持为 `http://mark.cloud-xl.top:9526`
- 重新执行 `npm -w apps/web run build`
3) **重启后端**
- `sudo systemctl restart browser-bookmark-server`
4) **更新扩展包**
- 重新执行「生成并发布扩展包」步骤
5) **若修改 Nginx 配置**
- 重新创建容器（见第 4/5 步）
6) **验证**
- 按第 8 步执行检查