Xu_BrowserBookmark/README.md

# 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`