175 lines
4.5 KiB
Markdown
175 lines
4.5 KiB
Markdown
# 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`
|