安装 — AiHummer 文档

AiHummer 安装 主机本地. 安装从您的个人账户开始于 my.aihummer.ru：你注册，获得一个 个人安装链接 并在您的服务器上运行单个命令。安装脚本会下载适用于您的架构的签名包，并在下面放置单个安装根目录 ~/.aihummer （在运行安装程序的用户的主目录中），注册 systemd 单元，并可选择地提供 sidecar。在此过程中没有任何容器。

[!NOTE] 这是一次本地主机原生安装——在 systemd 下运行的发行版压缩包，不 Docker。网关、Sidecar 和插件各自作为独立的 systemd 运行服务。

[!NOTE] 在开始之前你需要准备的东西：

一 Linux 服务器（x86_64 或 arm64），你可以通过 SSH 访问；

sudo 权限（或安装无根权限的意愿——见下文）；

PostgreSQL 和 pgcrypto 扩展 — 或让安装程序提供一个用户模式集群（在无根模式下它会自行完成此操作）；

一个账户在 my.aihummer.ru 获取你的个人安装链接。

完整的需求清单在要求页面。

步骤 1：获取您的个人安装链接

没有公共安装脚本 — 安装链接是 个人的 并在您的账户门户中签发：

注册于 my.aihummer.ru (电话号码 + 密码；电子邮件也需要)。
打开安装屏幕上点击“获取个人安装链接”。
该门户显示了带有您的个人链接的可运行命令。

关于门户本身（账单详情、文件、计划）的更多信息，请参见个人账户页面。

步骤 2：一键安装

从“安装”屏幕复制命令并在您的服务器上运行它（Linux x86_64/arm64）:

curl -fsSL -o install.sh "<your personal install link>" && sudo bash install.sh

个人链接的形式为 https://my.aihummer.ru/dl/<token>/install.sh，并与您的账户绑定。

[!IMPORTANT] 该链接是一次性的：它只对一次安装生效。 安装程序一旦通过它取得 install.sh，链接即视为已用尽。再次运行同一条命令会返回「链接已被使用」错误——这是保护措施，而不是故障。应对办法： 打开门户中的「安装」界面重新生成一个链接，免费且即时。

30 天 指的是构件下载的期限，而不是重复安装：已经装好的实例在链接被用于安装很久之后，仍会通过它继续获取更新。

该脚本检测您的 CPU 架构，下载匹配的包以及其 .sha256 校验和和共同签署 .sig 签名，验证两者，解压安装根目录并注册网关服务。参见更新日志针对当前版本。

个人链接也 将该实例绑定到您的客户门户账户：安装程序会存储链接中的令牌，实例在首次向供应商注册时会发送该令牌，门户会自动将实例链接到您的帐户。您的电子邮件立即成为该实例的 已验证的联系方式 — 在网页界面中没有单独的“附加并验证电子邮件”步骤，并且许可证的交付无需人工操作。

[!WARNING] 您的个人链接是您分发的密钥。请勿发布：任何人持有该链接可以在令牌过期之前代表你下载构建版本。

安装根布局

所有内容都位于同一个目录之下。具体是哪一个，取决于您以何种方式运行安装程序：

安装方式	安装根目录	配置文件	服务运行身份
常规安装（使用 `sudo`）	`/home/.aihummer`	`/etc/aihummer/gateway.env`	专用服务账户 `aihummer`
无 root 权限（rootless）	`~/.aihummer`	`~/.aihummer/etc/gateway.env`	您自己的用户

常规安装不会把文件放进您的主目录，也不会以您的身份运行服务：它会创建一个专用的非特权用户 aihummer。这是有意为之——服务即使被攻破，也不会把您的个人文件交到攻击者手里。

两种模式下根目录内部的布局完全相同（下面展示的是常规安装）：

/home/.aihummer/
├── bin/        gateway binary and the aihummer CLI
├── etc/        configuration (gateway.env)
├── share/      static assets for the administration interface
├── sidecars/   optional STT/TTS/etc services
├── plugins/    installed marketplace plugins
├── systemd/    unit files (symlinked into /etc/systemd/system)
├── state/      runtime state
├── data/       blob/media storage
└── logs/       service logs

生成到的 systemd 单元文件 systemd/ 是 符号链接到 /etc/systemd/system/，所以它们是通过常规方式管理的 systemctl 命令。

无根安装

sudo/root 权限不是必需的。如果你运行安装命令 无需sudo，安装程序切换到无根模式：单元被注册在 systemd --user 范围（文件在 ~/.config/systemd/user)，那 aihummer CLI 和 cosign 登陆 ~/.aihummer/bin，以及如果 AIHUMMER_DATABASE_URL 未设置安装程序将在安装根目录内配置一个用户模式的 PostgreSQL 集群。服务由以下方式管理 systemctl --user ...要在主机启动时启动服务（不仅仅是在用户登录时），请启用持续运行：

loginctl enable-linger $USER

边车选择

轻量级媒体附加容器 — STT（faster-whisper）、TTS（edge-tts）和视频 —— 开箱即用安装没有任何问题或警告：往返语音可以立即使用。它们中的任何一个都可以通过环境变量禁用 AIHUMMER_SKIP_STT=1, AIHUMMER_SKIP_TTS=1, AIHUMMER_SKIP_VIDEO=1.

网页搜索（SearXNG）和浏览器（CloakBrowser）已内置于签名的发行包中，默认离线安装——安装程序不再询问它们。标志可以改变这一行为——这是完整列表：

旗	效果
`--no-search` / `--no-browser`	跳过这个边车
`--external-search=URL` / `--external-browser=URL`	使用此 URL 的现有服务，而不是安装
`--browser-engine=cloak\|chrome`	浏览器引擎（默认 `cloak`）
`--with-search` / `--with-browser`	自 v1.0.14 起已多余——这已经是默认行为
`--with-embedder`	安装语义嵌入器（选择加入: 拉取 PyTorch — 几百兆字节)

搜索和浏览器在没有 tty 的情况下也会安装：它们的内容来自发行包，无需访问互联网。两者的安装都不会阻断——如果内容缺失或 Python 版本不受支持，该服务只是保持未配置状态，安装绝不会中止。还可以启用嵌入器 AIHUMMER_WITH_EMBEDDER=1; 没有它，记忆将通过词汇回退搜索运行。用户界面语言由…设置 AIHUMMER_LANG=ru|en （否则安装程序会在 tty 上询问）。PostgreSQL 连接会在 tty 上提示；对于非交互式安装，请设置 AIHUMMER_DATABASE_URL 提前。在 tty 上，安装程序还提供从备份恢复的选项。

# 安装网关，带嵌入器，不带浏览器（搜索默认安装）
curl -fsSL -o install.sh "<your personal install link>" && sudo bash install.sh \
  --with-embedder --no-browser

因为边车是通过 URL 访问的，你可以自由地混合使用本地和外部边车，并将多个网关指向一个共享的边车。

如何校验构建的真实性

来自账户门户的个人链接始终安装当前发行版——这是标准且唯一的途径。没有所谓「更新的版本」可供挑选：您拿到的就是供应商为生产使用而发布的那一版构建。

每一个构件——无论是首次安装还是每次更新——都以针对您架构的 tar 包形式送达，并随附 .sha256 校验和与 .sig（cosign）签名。安装程序在解包任何内容之前会同时校验两者。您无需手动验证。

预期结果： 校验静默通过，安装继续进行。若其中任何一项未通过，安装程序会带着错误停止，并保持正在运行的版本不变——损坏或被替换的文件绝不会落到您的服务器上。

如果供应商邀请您加入早期测试计划，门户中的「安装」界面会出现一个切换开关，并为您选择的选项签发单独的链接，详见实例。

验证安装

安装程序完成后，检查服务和就绪端点：

systemctl status aihummer-gateway
curl -fsS http://localhost:8780/healthz
curl -fsS http://localhost:8780/readyz

/healthz 报告活跃状态和版本； /readyz 检查 PostgreSQL 并返回 503 当数据库无法访问时。打包的 aihummer CLI 还提供 aihummer status 和 aihummer doctor 用于快速健康概览。

成功安装后你会看到的内容： 这 aihummer-gateway 服务于 active (running)，一个 200 从 /healthz 和 /readyz，以及初始管理员密码在 /home/.aihummer/etc/initial-admin-password.txt（无 root 权限安装时为 ~/.aihummer/etc/initial-admin-password.txt）为首次登录.

生产清单

一个安装命令就可以让网关运行，但它是 尚未准备好投入生产. 在暴露它之前，先完成：

传输层安全 — 在网关前终止 HTTPS（反向代理 / 你自己的）证书）；永远不要在不受信任的网络上暴露普通端口。
🔴 在反向代理上启用 WebSocket 支持。 移动端和桌面应用通过 wss:// 连接网关，因此代理必须透传 Upgrade 和 Connection 标头。未做该设置的代理会返回状态码为 200 的普通页面，而不是 101 Switching Protocols —— 应用会将其读作「服务无响应」，而实际上网关运行正常，日志里没有任何错误。在 Nginx Proxy Manager 中这是对应 Proxy Host 的 Websockets Support 开关；在普通 nginx 中则是 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; 以及 location 块中的 proxy_http_version 1.1。

用一条命令检查（预期 101，而不是 200）：
```
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  https://您的域名/
```
更改管理员密码 并删除 initial-admin-password.txt; 设置一个认证颁发者（AIHUMMER_OIDC_ISSUER / LDAP / SAML) 在公开之前 /admin/*.
备份主密钥和数据库 — 记录 AIHUMMER_MASTER_KEY （秘密如果没有它将无法恢复) 并设置定期的 PostgreSQL 备份。
连接一个真实模型 — 设置 AIHUMMER_LLM_* （或 BYOK）；没有它，回复就会出现来自确定性的模拟。
至少连接一个频道 (电报开始)并将代理绑定到它。

看首次登录, 配置和备份与灾难恢复详情请参阅。

如果它不起作用

「链接已被使用」/ 安装无法第二次运行 — 该链接是一次性的，先前的尝试已经把它用掉了。请在门户的「安装」界面重新生成一个，然后再次运行该命令。
curl: (22) … 404 或「链接无效」 — 链接复制不完整，或者其期限已过。补救办法相同：换一个新链接。
不受支持的架构 — 安装支持 Linux x86_64 和 arm64；其他平台没有捆绑包。
/readyz 返回 503 ——网关无法看到 PostgreSQL。请检查 AIHUMMER_DATABASE_URL、数据库可达性，以及那 pgcrypto 扩展被创建（CREATE EXTENSION IF NOT EXISTS pgcrypto;).
服务未启动 — 检查 systemctl status aihummer-gateway 和 journalctl -u aihummer-gateway；用于快速诊断运行 aihummer doctor.
未使用 sudo 安装，退出登录后服务停止 — 启用停留： loginctl enable-linger $USER （参见无根的).
签名验证失败 — 不要继续安装；稍后重试或获取一个新的链接。工件总是会被验证 .sha256 和共同签署 .sig.

接下来去哪儿

第一次运行：看首次登录取回初始管理员密码来自 /home/.aihummer/etc/initial-admin-password.txt（无 root 权限安装时为 ~/.aihummer/etc/initial-admin-password.txt）.
调整部署：阅读配置.
想要一次有指导的首次运行吗？使用快速入门.