先装 LinX，还是先部署 Xpod

这一页只讲两件事：怎么开始用 LinX，怎么把 Xpod 部署起来。应用读写数据放在单独的读写指南里，因为它要先有一个连得上的 Pod。

如果想先弄清三者各自负责什么，可以看 LinX、Xpod 和 drizzle-solid 各管什么。

下面两条路的前提和命令都来自官方公开资料。Xpod 部分引用的是官方 README 的原文，我们没有实际执行过；LinX 目前没有已验证的桌面安装包。哪些是官方说法、哪些还没核实，文中逐条标出来。

使用 LinX

LinX 是你每天打开的那个客户端。你给它材料和自己的要求，它给出结果，你再改到能用。

先确认这三件事

• 设备与系统：先看版本发布记录里有没有你这台机器能用的安装包。写这一页时，最新一条是 linx-v0.3.33（发布于 2026-06-30），只带一个 undefineds-co-linx-0.3.33.tgz。
• 账户与登录：登录和连接方式取决于你实际使用的服务。我们没有验证过任何注册或登录流程，这一页也不承诺账号、额度或价格。
• 网络：本机能访问你选择的 Pod 地址，也能访问 GitHub 下载发布文件。

最新那条发布里的 .tgz 是包文件，不是桌面安装程序。它可以用于构建和集成，但不等于「下载下来双击就能用」。因此这一页不会写「打开安装包、一路下一步」这类步骤。

目前的安装入口

• 可核对的正式入口是版本发布记录。每条记录会列出 tag 和对应文件。
• 如果某条记录里有你平台和架构的安装包，按那一条的说明安装。
• 如果只有 .tgz 这类包文件，它就不是可以直接运行的桌面程序，请不要当成安装包使用。
• 在本站核实到真实可下载、可安装的包之前，下载页会保持空状态，不放假的下载按钮。

首次启动与第一项任务

因为我们还没有执行过一次桌面安装，这里不写界面操作。等你拿到可用版本，可以按下面的顺序做第一件小事。步骤说的是任务本身，不是某个按钮的位置；如果某一步在你的版本里不存在，说明这项能力还没有交付。

1. 准备材料：找出这一周可以给出去的东西，比如几条会议记录、一份进度清单、两封待跟进的邮件。
2. 说清要求：「先写结论，分清已完成、卡住的事和下周安排。没确认的日期先留空。」
3. 看结构：结果里应当能分清本周完成、当前阻碍、需要决定、下周安排这四块。
4. 只改一处：挑一条不合你意的表述，比如「第二项还没定，改成待确认，客户名字先去掉」，再要一版新的结果。

怎样算成功

• 你给的材料里有内容出现在结果里，而不是拿到一份通用模板。
• 你明确提出过的一条要求（比如结论放最前面）在结果里能看出来。
• 改过一处之后拿到的是新的一版，而不是要你自己从头改。

如果有一条不成立，先记下你的系统、架构、版本，以及去掉个人资料和凭据之后的错误信息。

遇到问题去哪里

• 安装、启动、连接的问题：LinX 问题列表。提交时写清系统与架构、版本号，以及经过脱敏的错误信息。
• 想先了解 LinX 的工作方式：LinX 页面。
• 想知道装完之后数据存在哪、谁能看：保存、访问和迁移说明。

自部署 Xpod

Xpod 是保存数据、提供接口的那一层。它跑在你自己的机器或服务器上，所以部署前先把运行环境和依赖准备好。

下面所有命令和配置项都摘自官方 README 与仓库文件。我们引用了原文，没有执行过任何一次部署，请以仓库当前版本为准。

需要什么

官方 README 写明的要求：

• Bun 1.3+。从源码构建时，Bun 是主要的包管理器和任务执行器。
• Node.js 22+。如果只使用发布到 npm 的包，运行时有 Node 就够。
• Node 的 ABI 说明里写的范围是 >=22 <27。非交互式 shell、CI 和编辑器任务可能从 PATH 里取到别的 Node，启动前先确认版本。

两种部署档（README 的 Deployment Profiles）：

• local：SQLite 加本地磁盘，不需要 Redis 或 MinIO。适合个人使用、本地开发和本地应用接入。
• cloud：PostgreSQL、MinIO、Redis。README 说这一档面向多用户托管，带额度和用量相关的基础设施，以及节点协调、DNS 和可达性支持。

准备配置

1. 安装依赖并构建：

   bun install
   bun run build

2. 复制环境变量模板：

   # 本地模式
   cp example.env .env.local
   
   # 云端模式
   cp example.env .env.cloud

3. 变量名以仓库里的 example.env 为准。README 里出现过的相关命名包括 XPOD_DEFAULT_*（默认额度一类）。具体取值和适用条件我们没有核实，请按官方文件和你的实际部署决定。

4. 先过一遍 ABI 检查，避免 Node 版本不对引起的本地模块报错：

   nvm use
   bun run check:abi

启动

本地模式：

bun run local

README 说明启动后访问 http://localhost:3000/。

云端模式：

bun run cloud

也可以打成单文件再运行（README 的 Single-File Packaging）：

# 自解压启动器，产出 .artifacts/xpod-single.cjs
bun run build:single:standalone
node .artifacts/xpod-single.cjs --mode local

# Bun 原生二进制，产出 dist/xpod-bun
bun run build:single:bun
dist/xpod-bun --mode local --port 5710

README 还提到，在支持的 Unix 平台上，npm install @undefineds.co/xpod 可以解析到对应的原生 xpod 二进制平台包。

检查服务是否起来了

• README 的库模式示例用 /service/status 判断运行时是否可用：请求返回成功（示例里判断 response.ok）就算起来了。本地模式可以先打开 http://localhost:3000/，再看这个路径。
• 登录与身份：Xpod 把 Pod 资源、WebID 身份和访问控制放在核心位置。第一个账号怎么建、第一次登录怎么做，README 没有给出逐步说明，请按 Xpod 仓库的文档目录确认对应材料。我们未执行，无法替你确认这一步。

数据存在哪，怎么备份

• local 档：数据落在 SQLite 文件和本地磁盘上，备份就是备份这两处。具体路径由你的配置决定，README 没有写死。
• cloud 档：PostgreSQL 和 MinIO 承担持久化，Redis 用于协调。README 只说明了依赖构成，没有给出备份步骤，所以我们不在这里编造备份命令。上线前请按官方部署文档确定数据库与对象存储的备份方式。

常见问题和官方排错入口

• 原生模块报错或 NODE_MODULE_VERSION 不一致：多半是 Node 版本不对。按 README 的做法，在同一个 Node 大版本下重装：

  nvm use
  bun install --force

• 命令找不到或行为异常：确认 PATH 里的 Node 落在 >=22 <27，Bun 是 1.3+。

• 部署档和依赖的更多说明：docs/deployment-modes.md。

• 其他问题：Xpod 问题列表。

想先比较云端和自部署该怎么选，见 Xpod 页面；保存位置、访问权限和迁移范围写在保存、访问和迁移说明。