内容
<div align="center">
<img src="assets/banner.svg" alt="REFUGIO — 一个自托管的AI避难所" width="100%">
<p>
<img src="https://img.shields.io/badge/macOS%20·%20Linux%20·%20Windows-f4f2ee?style=flat-square&labelColor=000000" alt="跨平台">
<img src="https://img.shields.io/badge/本地%20LLM-Ollama%20%2F%20LM%20Studio-ff0018?style=flat-square&labelColor=000000" alt="本地LLM">
<img src="https://img.shields.io/badge/连接器-MCP-ff0018?style=flat-square&labelColor=000000" alt="MCP连接器">
<img src="https://img.shields.io/badge/许可证-MIT-a8a5a0?style=flat-square&labelColor=000000" alt="MIT许可证">
</p>
**一个自托管的AI避难所 — 完全在您的机器上运行。**
<sub> <a href="https://phantazein.com">Phantazein</a> 工具包的一部分 </sub>
</div>
---
<table>
<tr>
<td><a href="#安装">📦 安装</a></td>
<td><a href="#本地LLM引擎">🧠 LLM引擎</a></td>
<td><a href="#连接器">🔌 连接器</a></td>
<td><a href="#日常使用">⚡ 日常使用</a></td>
<td><a href="#自定义域名">🌐 域名</a></td>
</tr>
</table>
一条命令安装一个**本地LLM**（Ollama或LM Studio）和[Open WebUI](https://github.com/open-webui/open-webui)，为您提供一个私有的、自托管的AI助手，无需云服务，无需API密钥，也无需数据离开您的计算机。可选的[模型上下文协议](https://modelcontextprotocol.io/)连接器将其连接到您的办公工具 — Slack、Notion、Jira、ServiceNow、Salesforce和持久内存。
适用于 **macOS、Linux和Windows**。无需先决条件 — 安装程序处理所有内容（Node.js、Python、Git、LLM引擎、模型和Open WebUI）。
> **概念验证。** 预计会有粗糙的边缘和突破性的变化。欢迎反馈！
## 安装
### macOS / Linux
```bash
curl -fsSL https://raw.githubusercontent.com/Phantazein-apps/refugio/main/install-refugio | bash
```
### Windows (PowerShell)
```powershell
irm https://raw.githubusercontent.com/Phantazein-apps/refugio/main/install-refugio.ps1 | iex
```
### 发生了什么
1. 安装 **Node.js**、**Git** 和 **[uv](https://docs.astral.sh/uv/)** （一个快速的Python管理器，带有自己的Python），如果缺少
2. 克隆REFUGIO到 `~/refugio`
3. 设置您的 **本地LLM引擎**：
- 自动安装 **[Ollama](https://ollama.com/)** 并为您的机器内存下载模型，**或**
- 允许您选择 **[LM Studio](https://lmstudio.ai/)** 代替（连接到其本地服务器 `:1234`；自动检测和首选，如果已经运行）
4. 引导您完成可选的连接器凭证（Slack、Notion、Jira等）和内存后端
5. 在隔离的虚拟环境中安装 **Open WebUI**
6. 可选地设置 **https://refugio** 作为本地域名（mkcert + Caddy）
7. 启动所有内容，创建您的帐户并打开浏览器 — 已经登录
> **重新安装？** 再次运行相同的命令。您的设置在 `~/.refugio.env` 中保留。
### 安装后
在内存充足的机器上，REFUGIO **自动启动登录**。在 **低内存（≤ 8 GB）** 机器上，它改为 **按需运行** — 这样它在您不使用时不会占用内存（使用 `refugio` 启动，使用 `refugio stop` 停止）。
1. 打开 **https://refugio** （或 **http://refugio.localhost:8080** 在macOS/Linux上 — **http://127.0.0.1:8080** 在Windows上 — 如果您跳过了自定义域名）— 您已经登录
2. 开始聊天 — 您的本地模型已准备就绪
3. 如果您添加了连接器，请在聊天框中点击 **扳手图标** 以使用工具
## 本地LLM引擎
REFUGIO在您的机器上运行模型 — 没有任何内容发送到任何外部服务。
- **Ollama** （默认）自动安装并为您下载模型。
- **LM Studio** — 在安装程序中选择它以连接到LM Studio的本地服务器（兼容OpenAI，位于 `http://localhost:1234`）。首先启动服务器（LM Studio → 开发者 → 启动服务器）；安装程序还会自动检测并默认为其已经运行时。
### 模型自动选择
安装程序根据您的系统内存选择一个具有工具调用功能的Ollama模型：
| 系统内存 | 默认模型 | 近似下载 |
|------------|---------------|---------------|
| ≤ 8 GB | `llama3.2:1b` | ~0.8 GB |
| 9–16 GB | `llama3.2:3b` | ~2 GB |
| 17–32 GB | `llama3.1:8b` | ~4.7 GB |
| 33–48 GB | `qwen2.5:14b` | ~9 GB |
| > 48 GB | `gpt-oss:20b` | ~13 GB |
大小考虑了macOS + 您的其他应用程序，而不仅仅是总内存。在 **≤ 8 GB** 机器上，REFUGIO还在您停止聊天后不久卸载模型（以便它不会占用内存）。
**两个层级，自动切换。** 上表是 **最佳** 模型（根据总内存调整大小）。安装程序还会下载一个较轻的 **伴侣** 模型，降一个层级 — 例如，在16 GB Mac上为 `llama3.2:3b` + `llama3.2:1b`，或在8 GB上为 `llama3.2:1b` + `qwen2.5:0.5b`。每次REFUGIO启动时，它都会测量实际 **可用** 内存（在其他应用程序加载后），并 **激活当前安装的模型**：当有空间时使用最佳模型，当机器繁忙时使用较轻的模型。如果即使是最小的模型也很紧张，它仍然会运行并告诉您关闭一些应用程序。启动时无需下载，无需调整，无需故障排除。
在模型选择器中，每个模型都标有您的 **当前** 空闲内存 — 活动模型显示 **✓**，而需要比空闲内存更多的RAM的模型显示 **⚠ 需要 ~N GB 空闲** 以及其描述中的警告，以便手动切换到过重的模型是有根据的选择。
> 在Apple Silicon上，请确保Ollama是 **arm64** 版本 — x86_64/Rosetta Ollama运行在CPU上（无Metal GPU），对于除最小模型之外的任何模型都太慢了。
使用 `ollama pull <model>` 随时拉取更多模型，然后在模型选择器中选择它们。要在安装时覆盖默认值，请设置 `REFUGIO_MODEL` （例如 `REFUGIO_MODEL=llama3.1:8b`）。
## 连接器
所有连接器都是 **可选的** — 仅配置您需要的连接器，或全部都不配置。
| 服务器 | 端口 | 工具 |
|--------|------|-------|
| **Slack** | 3001 | `search_messages`, `get_channel_history`, `list_channels`, `get_thread` |
| **Notion** | 3002 | `search`, `get_page`, `get_block_children`, `query_database` |
| **Jira** | 3003 | `search_issues`, `get_issue`, `get_projects` |
| **内存** | 3004 | 见下文 |
| **ServiceNow** | 3005 | `query_table`, `get_record`, `list_tables` |
| **Salesforce** | 3007 | `soql_query`, `get_record`, `search`, `describe_object`, `list_objects` |
工具通过 [MCPO](https://github.com/open-webui/mcpo) （MCP到OpenAPI代理）暴露给Open WebUI。
### 内存
内存根据您的RAM扩展：
- **16 GB+ → [MemPalace](https://github.com/MemPalace/mempalace)** （默认）— 本地优先语义内存（ChromaDB + 本地嵌入模型）；没有任何内容离开您的机器。通过精简的2工具包装器（`memory_search` / `memory_save`）公开，以便小型模型不会被其33个工具淹没。
- **≤ 8 GB → GitHub支持（PACK样式）** — MemPalace的嵌入（~1.5 GB）对于这里的模型来说太重了，因此提供了一个较轻的后端：一个markdown内存文档通过捆绑的 `servers/memory.js` 同步到一个私人的GitHub仓库（`get` / `update`），**没有本地嵌入（~0 RAM）**。需要一个细粒度的PAT，具有内容读取/写入权限 — 或选择 **无** 仅限模型。
## 日常使用
**舒适的RAM（> 8 GB）：** REFUGIO 自动启动登录。要手动启动：
```bash
node ~/refugio/start-refugio.cjs # 或：cd ~/refugio && npm start
```
**低RAM（≤ 8 GB）：** REFUGIO **按需运行**，以便它不会占用 ~0.6 GB 的内存。（模型本身始终在第一次聊天时延迟加载，并在之后不久卸载 — 启动时永远不会加载模型 — 因此空闲成本仅为 Open WebUI，当您退出时，空闲模式会释放内存）。
```bash
refugio # 启动它（打开浏览器）
refugio stop # 停止所有内容并释放内存
refugio status # 它正在运行吗？
# 或双击“启动 REFUGIO.command”（macOS）/“Start-REFUGIO.bat”（Windows）
```
要重新配置或更新，请再次运行安装程序。
### 菜单栏应用（macOS）
一个小型原生菜单栏应用为非技术用户提供了一键式 **启动 / 停止 / 打开** 控制，**登录时启动** 切换开关和 **退出** — 无需终端。它只是驱动现有的 `~/refugio` 监督程序（退出应用 **不** 停止 REFUGIO；使用 **停止**）。
```bash
cd ~/refugio/menubar && ./install.sh # 构建 REFUGIO.app → /Applications，启动它
```
需要 Swift 工具链（`xcode-select --install`）。在菜单栏中查找 **山** 图标。
**自动启动详情（> 8 GB）：**
- **macOS**: launchd (`~/Library/LaunchAgents/com.phantazein.refugio.plist`)
- **Linux**: systemd 用户服务 (`~/.config/systemd/user/refugio.service`)
- **Windows**: 启动文件夹 (`REFUGIO.vbs`)
- **日志**: `~/.refugio-logs/refugio.log` 和 `~/.refugio-logs/refugio.err`
## 自定义域名
在安装过程中，您可以设置 **https://refugio** 作为本地快捷方式：
- 使用 [mkcert](https://github.com/FiloSottile/mkcert) 进行本地信任的TLS + [Caddy](https://caddyserver.com/) 作为反向代理
- 需要一次管理员密码（用于证书和 `/etc/hosts` 条目）
- 在重新安装时自动恢复
- 没有它，REFUGIO 在 **http://refugio.localhost:8080** 在macOS/Linux上可用（在Chrome、Firefox、Edge中有效，无需设置），或 **http://127.0.0.1:8080** 在Windows上
## 工作原理
### 安装程序链
```
curl | bash
→ install-refugio（bash） 安装 Node.js + Git
→ install-node.cjs（node） 安装 uv，克隆存储库，设置LLM引擎，
凭证，Open WebUI，并启动所有内容
→ configure-owui.cjs 配置 Open WebUI（帐户，提示，工具，模型）
```
### 架构
```
浏览器 → https://refugio（Caddy）→ Open WebUI（:8080） ─┬─→ Ollama / LM Studio（本地模型）
└─→ MCPO（:8010）→ MCP服务器（:3001–3007）→ API
```
- **所有内容都在本地运行。** 模型、UI和连接器服务器都在您的机器上运行。
- **Open WebUI** 在 `uv` 管理的Python虚拟环境中原生运行（无Docker）。
- **MCP服务器** 作为 detached Node.js进程运行，由 `start-refugio.cjs` 监督（崩溃后自动重启）。
- **凭证** 存储在 `~/.refugio.env` （chmod 600）。
- **系统提示** 根据您启用的连接器自动生成。
## 手动设置
### 1. 克隆和安装
```bash
git clone https://github.com/Phantazein-apps/refugio.git ~/refugio
cd ~/refugio
npm install
```
### 2. 配置凭证
创建 `~/.refugio.env` （或运行安装程序，它为您编写）：
```bash
# -- LLM 引擎 --
REFUGIO_ENGINE=ollama
OLLAMA_BASE_URL=http://localhost:11434
REFUGIO_MODEL=llama3.1:8b
# 使用LM Studio代替：
# REFUGIO_ENGINE=lmstudio
# OPENAI_API_BASE_URL=http://localhost:1234/v1
# OPENAI_API_KEY=lm-studio
# -- 您的账户 --
OWUI_NAME=
OWUI_EMAIL=
# -- Slack（需要用户令牌进行搜索） --
SLACK_TOKEN=xoxp-...
# -- Notion --
NOTION_TOKEN=ntn_...
# -- Jira --
JIRA_DOMAIN=yourcompany.atlassian.net
JIRA_EMAIL=you@yourcompany.com
JIRA_API_TOKEN=...
# -- ServiceNow --
SERVICENOW_INSTANCE=yourcompany.service-now.com
SERVICENOW_USERNAME=your.username
SERVICENOW_PASSWORD=...
# -- Salesforce --
SALESFORCE_INSTANCE_URL=https://yourcompany.my.salesforce.com
SALESFORCE_USERNAME=your.username
SALESFORCE_PASSWORD=...
SALESFORCE_SECURITY_TOKEN=...
# -- 内存 --
# MemPalace（本地）：REFUGIO_MEMORY=mempalace
# GitHub支持： REFUGIO_MEMORY=github + 以下GITHUB_*值
REFUGIO_MEMORY=mempalace
GITHUB_TOKEN=
GITHUB_OWNER=
GITHUB_REPO=
GITHUB_MEMORY_PATH=MEMORY.md
```
### 3. 单独启动服务器
```bash
cd ~/refugio
node servers/slack.js --http # 端口 3001
node servers/notion.js --http # 端口 3002
node servers/jira.js --http # 端口 3003
node servers/memory.js --http # 端口 3004（GitHub支持的内存）
node servers/servicenow.js --http # 端口 3005
node servers/salesforce.js --http # 端口 3007
```
覆盖端口：`MCP_SSE_PORT=4000 node servers/slack.js --http`
验证服务器：`curl http://localhost:3001/health`
## 服务器模式
所有服务器支持三种传输方式：
| 模式 | 标志 | 用例 |
|------|------|----------|
| 流式HTTP | `--http` | Open WebUI和大多数MCP客户端 |
| SSE | `--sse-only` | 旧MCP客户端 |
| stdio | *(无)* | Claude Desktop和其他基于stdio的MCP客户端 |
## 项目结构
```
├── install-refugio # Bash引导程序（安装Node + Git，运行安装程序）
├── install-refugio.ps1 # Windows的PowerShell引导程序
├── install-node.cjs # 主要安装程序（跨平台）：LLM引擎，OWUI，连接器
├── start-refugio.cjs # 进程监督器（LLM，MCP服务器，Open WebUI，Caddy）
├── scripts/
│ ├── configure-owui.cjs # 自动配置Open WebUI（帐户，提示，工具，模型）
│ └── google-auth.js # 一次性Google OAuth2设置（可选的内存同步）
├── server.js # 全功能MCP服务器（所有工具都在一个端口上）
├── servers/
│ ├── shared.js # 共享传输，启动和错误处理
│ ├── slack.js # Slack MCP服务器
│ ├── notion.js # Notion MCP服务器
│ ├── jira.js # Jira MCP服务器
│ ├── memory.js # GitHub支持的内存MCP服务器
│ ├── servicenow.js # ServiceNow MCP服务器
│ └── salesforce.js # Salesforce MCP服务器
├── connectors/ # 服务器使用的API连接器
├── branding/ # REFUGIO徽标和图标资产
└── package.json
```
## 构建工具
100% 使用 [Claude](https://claude.ai/) 编码。
## 许可证
MIT
---
<div align="center">
<sub>由 <a href="https://phantazein.com">Phantazein</a> 构建 · <a href="https://github.com/Phantazein-apps">更多工具 →</a></sub>
</div>
