# siyuan-desktop

**Repository Path**: delay/siyuan-desktop

## Basic Information

- **Project Name**: siyuan-desktop
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SiYuan Desktop

局域网内自托管 [SiYuan Note](https://b3log.org/siyuan/)（思源笔记）的多节点桌面客户端。
在一个窗口里管理多台 SiYuan 服务实例，支持一键切换、健康检查、最近文档面板与系统托盘。

基于 **Electron（内置 Chromium）** 构建，macOS / Windows 一致运行官方桌面版 Web UI，兼容性最佳。

---

## 特性

- **多节点管理**：在同一客户端中登记任意数量的自托管 SiYuan 实例（局域网 / 远程均可）。
- **快速切换**：通过侧边栏、命令面板（Ctrl/Cmd+K）或系统托盘菜单，一键切换当前节点，WebView 自动重载。
- **打开即解锁**：自动注入凭证，绕过思源锁屏。支持两种认证模式：
  - `token`：注入 `Authorization: Token <token>`，内核直接授予管理员，**跳过锁屏**。
  - `authCode`：懒加载 `POST /api/system/loginAuth` 获取 `siyuan` cookie 并缓存复用。
- **凭证安全存储**：节点地址 / 名称 / 认证模式等元数据存于 `nodes.json`，密码 / Token 存入系统钥匙串（keytar），不落明文文件。
- **最近文档面板**：读取 `/api/storage/getRecentDocs` 展示近期文档（复制 ID 以便深链）。
- **系统托盘**：关闭窗口最小化到托盘，托盘菜单可直接切换节点。
- **开机自启**：通过 `auto-launch` 管理。
- **本地反向代理**：主进程内置代理转发 HTTP + WebSocket，并剥离 SiYuan 响应的 `CSP` / `X-Frame-Options`，WebView 永远只加载 `http://127.0.0.1:<port>`。

---

## 架构

```
┌─────────────────────────────────────────────────────────────┐
│  Renderer (React + Vite)                                      │
│   src/App.tsx, src/components/*                               │
│   └─ 通过 window.electronAPI.invoke(cmd, args) 调用主进程      │
└───────────────────────────┬─────────────────────────────────┘
                            │ contextBridge (electron/preload.cjs)
┌───────────────────────────┴─────────────────────────────────┐
│  Main Process (Node, electron/main.cjs)                       │
│   • 窗口 / 托盘 / 自启 / IPC 桥接                              │
│   • 本地反向代理 (electron/proxy.cjs)：HTTP + WS 转发          │
│   • 节点存储 + 钥匙串 (electron/store.cjs)                    │
│   • 注入认证、剥离 CSP / XFO                                  │
└───────────────────────────┬─────────────────────────────────┘
                            │ http://127.0.0.1:<port>
                    ┌───────┴────────┐
                    │  SiYuan Kernel  │  (自托管实例，可多个)
                    │  (Chromium UI)  │
                    └────────────────┘
```

> **为什么是 Electron 而非 Tauri**：原 Tauri 2 + Rust 方案在 macOS 上受限于 WKWebView（WebKit），
> 运行思源兼容性差；而 Tauri 在 macOS 无法切换到 Chromium。为获得一致的 Chromium 体验，项目迁移到了
> 纯 Node 后端的 Electron 方案（原 `src-tauri/` 已移除）。

| 模块 | 文件 | 职责 |
| --- | --- | --- |
| 主进程入口 | `electron/main.cjs` | 窗口、托盘、自启、IPC 注册、siyuan 启动通道 |
| 反向代理 | `electron/proxy.cjs` | HTTP/WS 转发、认证注入、剥离 CSP/XFO |
| 节点存储 | `electron/store.cjs` | `nodes.json` + keytar 钥匙串、URL 归一化 |
| 预加载 | `electron/preload.cjs` | 暴露 `window.electronAPI` |
| 桥接层 | `src/electron-api.ts` | 渲染端调用主进程的命令封装 |
| 前端 | `src/App.tsx` + `src/components/*` | UI、节点管理、切换面板 |

---

## 技术栈

- **运行时**：Electron 33（Chromium WebView）
- **前端**：React 18 + TypeScript + Vite 5
- **后端**：Node（主进程），`http-proxy`、`keytar`、`auto-launch`、`node-fetch`
- **打包**：electron-builder（macOS `.dmg` / Windows `.nsis`）

---

## 目录结构

```
siyuan-desktop/
├── electron/                 # 主进程（Node）
│   ├── main.cjs              # 窗口 / 托盘 / 自启 / IPC
│   ├── proxy.cjs             # 本地反向代理（HTTP + WS）
│   ├── store.cjs             # 节点存储 + 钥匙串
│   ├── preload.cjs           # contextBridge 桥接
│   └── assets/               # 图标（icon / tray）
├── src/                      # 渲染端（React + Vite）
│   ├── App.tsx
│   ├── electron-api.ts       # 主进程桥接封装
│   ├── components/           # 侧边栏 / 设置 / 面板 / 命令面板
│   └── main.tsx / styles.css
├── tools/
│   └── make_icons.py         # 生成 electron/assets 图标集
├── index.html
├── vite.config.ts
├── tsconfig.json
└── package.json
```

---

## 快速开始

### 前置要求

- Node.js 18+（推荐 20+）
- 一台或多台已运行的 SiYuan 实例（开启了 API / 访问授权码）

### 安装

```bash
npm install
```

> `npm install` 会下载 Electron 二进制，首次较慢。

### 开发模式

```bash
npm run dev
```

同时启动 Vite dev server（端口 `1420`）与 Electron 联调（`ELECTRON_DEV=1`）。

### 构建（仅前端打包）

```bash
npm run build        # tsc + vite build → dist/
```

### 打包为安装包

```bash
npm run dist         # 先 build，再用 electron-builder 生成 release/
```

- macOS：`release/SiYuan Desktop-*.dmg`
- Windows：`release/SiYuan Desktop-*-setup.exe`

### 仅运行（已安装依赖）

```bash
npm start
```

---

## 环境变量

| 变量 | 说明 |
| --- | --- |
| `ELECTRON_DEV=1` | 开发模式（加载 Vite dev server，而非 `dist/`）。 |

> 窗口控件由操作系统原生提供，wrapper 不再自绘标题栏：macOS 使用原生红绿灯（左上），Windows 使用原生最小化/最大化/关闭（右上）。承载思源 UI 的 iframe 内部仍由思源自绘并接管其控件（`siyuan-cmd` 桥接）。节点管理入口（添加/切换/最近文档）位于左侧栏。

---

## 添加 / 管理节点

在应用内「设置」中添加节点：

- **名称**：本地显示用。
- **URL**：SiYuan 内核地址，如 `http://192.168.1.10:6806`。
- **认证模式**：
  - `token`：填写 API Token（设置 → 关于 → API token）。
  - `authCode`：填写访问授权码（Docker 的 `--accessAuthCode` / `SIYUAN_ACCESS_AUTH_CODE`）。
- **备注**：可选。

凭证存于系统钥匙串，删除节点会一并清除对应凭证。

---

## 平台说明与安全

- **macOS / Windows 一致**：均使用 Electron 内置 Chromium 渲染思源官方桌面 UI。
- **iframe 必须跑桌面模式（带 Node）**：思源内核 UI 启动阶段会 `require('electron')`，
  故承载它的窗口固定开启 `nodeIntegration`，且 proxy 负责剥离思源响应的 CSP/XFO。
- **自签名证书**：代理对 HTTPS 节点使用 `rejectUnauthorized:false`，兼容自签名证书。
- **凭证保护**：Token / 授权码不写入 `nodes.json`，仅存系统钥匙串。

---

## 常用脚本

| 命令 | 作用 |
| --- | --- |
| `npm run dev` | 开发联调（Vite + Electron） |
| `npm run build` | 类型检查 + 前端打包 |
| `npm run dist` | 打包为 dmg / nsis 安装包 |
| `npm start` | 直接启动 Electron（使用 `dist/`） |
| `npm run preview` | 预览前端构建产物 |

---

## 许可证

私有项目。