Windows 桌面版

把整套服务端打包成一个 Windows 可执行程序：双击启动，弹出原生窗口直接进管理界面，不需要装 Python、不需要 Docker、不需要 nginx。数据库仍由你自备。

桌面版不自带数据库它自带 Python 运行时、全部依赖、前端产物和三个服务进程，但 PostgreSQL 与 Redis 需要你事先准备好（本机安装、局域网或远程均可）。首次启动会弹出图形配置向导，填写连接信息并当场测试连通性。ClickHouse 可以不装。

本页目录这是什么先准备数据库安装与首次启动配置向导文件与数据位置内部结构能力边界自行构建故障排查

1. 这是什么

桌面版和 Docker 部署跑的是同一套服务端代码，没有裁剪功能、没有分支版本。区别只在外壳：

	Docker 部署	Windows 桌面版
启动方式	`docker compose up -d`	双击 `AiLubricant.exe`
访问方式	浏览器打开 `:3006`	程序自带原生窗口，自动打开管理端
Python 环境	容器内	已内置，目标机无需安装
前端静态资源	nginx 或容器内	程序内置，无需 nginx
PostgreSQL / Redis	Compose 自动创建	需自备，向导中填写连接
ClickHouse	可选 profile	可选，留空即关闭

适合的场景是单机自用与本地评估：想在自己的 Windows 上跑一套模型网关，管理渠道、账号池、API Key 和请求日志，不想碰 Docker 和命令行。生产多用户部署仍推荐 Docker Compose。

2. 先准备数据库

桌面版启动前必须有可连接的 PostgreSQL 和 Redis。二者都不是可选项：PostgreSQL 存放渠道、账号、API Key、模型路由和平台配置，Redis 存放限流计数、并发租约、冻结状态与会话。

PostgreSQL

用官方 Windows 安装包即可（postgresql.org），版本 14 以上。安装时记住端口、用户名和密码，并创建一个空库（例如 ai-lubricant）。

Redis（注意版本下限）

Redis 必须 6.0 或更高平台使用的 Redis 客户端在建立连接时强制发送 HELLO 3 握手，而 HELLO 命令是 Redis 6.0 才引入的，没有向下兼容路径。早年的 Windows 移植版停留在 3.x，无法使用。

Windows 上的三种可行做法：

Memurai——原生 Windows 服务，兼容 Redis 7，Redis 官方文档推荐的 Windows 方案。安装后默认监听 6379，开箱可用。
Docker——已经装了 Docker Desktop 的话最省事：docker run -d -p 6379:6379 redis:7-alpine。也可以直接用仓库里的 docker-compose.yml 同时起 PostgreSQL 和 Redis，桌面版只连它们。
WSL2——在 WSL 里 apt install redis-server，Windows 侧连 127.0.0.1:6379。

ClickHouse（可选，可以不装）

不配置时主链路完全正常，只有两项功能不可用：请求日志详情里的完整请求/响应原文，以及 Agent 与网页聊天的对话历史。渠道管理、API Key、用量计费、请求日志列表都不依赖它。

3. 安装与首次启动

桌面版是 onedir 形态：一个目录，里面是 AiLubricant.exe 和 _internal\ 依赖目录。整个目录一起复制才能运行，单独拷 exe 不行。

AiLubricant\
  AiLubricant.exe          <- 双击这个
  _internal\            <- Python 运行时、依赖、前端产物、服务端源码

把目录放到任意位置（例如 C:\Program Files\AiLubricant\ 或 D:\AiLubricant\），双击 AiLubricant.exe。

首次启动会慢几秒程序要初始化数据库表结构（约 50 张表，全部幂等），并按顺序拉起三个服务进程。窗口出现前请耐心等待，不要重复双击。

4. 配置向导

首次启动，或检测到数据库连不上时，窗口里会显示配置向导，而不是直接报错退出。向导包含三块：

PostgreSQL——主机、端口、用户、密码、库名。点「测试连接」会真实建连并返回服务端版本号。
Redis——主机、端口、库号。测试成功会显示 redis_version，便于确认版本是否满足 6.0 下限。
ClickHouse——留空即关闭。填了会测试连通性。

两项必需测试都通过后，「保存并启动」按钮才可用。保存会写入用户配置文件（见下一节），随后自动拉起服务并跳转到管理界面。以后启动如果连接仍然有效，就直接进管理界面，不再显示向导。

之后想改配置删除或编辑 %LOCALAPPDATA%\AiLubricant\.env，下次启动会重新走向导。也可以直接改这个文件里的连接字段。

5. 文件与数据位置

程序不往安装目录写任何东西——安装到 Program Files 时不会遇到权限问题。所有运行期数据都在用户目录下：

路径	内容
`%LOCALAPPDATA%\AiLubricant\.env`	数据库连接、自动生成的节点密钥与控制令牌
`%LOCALAPPDATA%\AiLubricant\logs\`	三个服务进程各自的日志：`main.log`、`node_server.log`、`tunnel_server.log`
`%LOCALAPPDATA%\AiLubricant\mc-tunnel-bins\`	穿透客户端二进制缓存（frpc / cloudflared / npc，首次使用时联网下载）
`%LOCALAPPDATA%\AiLubricant\node-bin\`	节点二进制缓存

.env 含凭据这个文件保存数据库密码、节点凭据主密钥和内部控制令牌。备份或反馈问题时不要整份外发；重装保留它可以避免重新配置，但主密钥丢失会导致已封存的节点凭据无法解密。

6. 内部结构

双击 exe 后，程序按固定顺序拉起三个服务进程，并用一个原生窗口显示前端：

主服务（127.0.0.1:8001）——对外 API、管理端、用户门户、MCP 运行时。窗口加载的就是它。
节点控制服务（127.0.0.1:8003）——接收节点主动连接。等主服务就绪后才启动。
穿透运行时服务（127.0.0.1:8004）——管理穿透客户端子进程。最后启动。

为什么必须串行启动主服务与穿透服务会各自对同一批穿透表做增量列对账，并发执行有小概率撞车。串行启动彻底规避，代价只是启动多等一两秒。Docker 部署里靠 depends_on + 健康检查达到同样效果。

三个服务默认只绑 127.0.0.1，不监听外网地址，因此不会触发 Windows 防火墙弹窗。关闭窗口时会先请求各进程优雅退出，并由作业对象（Job Object）确保连带回收穿透客户端等孙进程——即使主程序被强制结束也不会留下孤儿进程。

7. 能力边界

桌面版功能不打折，但单机运行有几个天然限制，事先知道能省掉排查时间：

远程节点连不进来节点是主动连接控制服务的。桌面机通常在 NAT 后面、没有公网地址，因此本机与局域网节点可用，公网远程节点无法接入，除非你自行做端口映射或先配好穿透。这是网络位置决定的，不是功能缺失。

穿透客户端需要联网——frpc / cloudflared / npc 不随程序打包，首次使用时从 GitHub 下载并缓存。离线环境需手动放入缓存目录。
单实例——桌面版按单机单实例设计。同一个数据库不要同时连多个桌面实例，穿透运行时的单写者租约会互相抢占。
端口占用——8001 / 8003 / 8004 被占会启动失败，日志里能看到绑定错误。

8. 自行构建

在装好开发环境的机器上（Python 3.12 + pnpm）：

powershell -ExecutionPolicy Bypass -File desktop\build.ps1

脚本依次做四件事：构建前端产物、选择 Python 解释器、安装打包依赖、执行 PyInstaller。产物在 dist\AiLubricant\。

打包配置里有两处必须留意其一，服务端用字符串路径动态注册数据模型，静态分析发现不了，全部在 AiLubricant.spec 的 hiddenimports 里显式声明；其二，protobuf 运行时会校验版本与生成代码是否匹配，不匹配直接硬失败，因此 requirements-desktop.txt 精确锁定了 protobuf 版本，不要放宽成范围。

9. 故障排查

第一件事永远是看日志：%LOCALAPPDATA%\AiLubricant\logs\ 下三个文件分别对应三个服务。

现象	原因与处理
双击后窗口一闪而过	看 `logs\main.log` 末尾。多为数据库连不上或端口被占。
向导里 Redis 测试报连接被拒	Redis 没启动，或端口不对。Memurai 装完确认服务已运行。
Redis 测试报协议/握手相关错误	Redis 版本低于 6.0。换 Memurai 或 Docker 版 Redis 7。
界面空白、样式全丢	安装目录不完整——`_internal\` 必须和 exe 同级完整存在。重新解压整个目录。
节点页面报服务不可用	节点控制服务没起来，看 `logs\node_server.log`；主服务本身不受影响。
穿透状态一直是 pending	穿透运行时没起来，看 `logs\tunnel_server.log`；或首次下载客户端二进制失败（需联网）。
请求日志详情看不到原文 / Agent 对话不可用	正常现象，未配置 ClickHouse。需要的话在 `.env` 里补上连接。