企业官网建设流程全解析

• 云原生
• 后端
• 运维

本文是一份面向系统管理员的完整实战指南，讲解如何从主机终端（键盘+显示器或 SSH 会话）用 Olares CLI 完成一台全新或未初始化的 Olares 设备（例如 Olares One）的安装与激活。读完本文，你将掌握olares-cli install安装命令、不同版本下激活工具的准备方式、olares-cli wizard frp的 FRP 主机查询，以及olares-cli wizard activate的完整激活命令与全部参数含义，并能结合源码理解激活流程背后的绑定与状态机实现。

:::warning 安全警告：请勿泄露命令与终端输出 该流程需要主机管理员权限，并要求提供你的 12 词助记词短语。不要分享命令本身、终端输出、截图或 shell 历史记录，因为它们可能暴露助记词短语和账户凭证。 :::

前置条件

在开始之前，请确认以下要求全部满足：

• 你可以通过键盘和显示器直接访问 Olares 设备，或者通过 SSH 登录该设备。
• 设备可以联网，以便下载软件包、查询 FRP 服务器并完成激活。
• 你可以以 root 用户身份运行命令，或者在命令前加sudo。
• 你已经使用 LarePass 应用创建了 Olares ID，并备份了你的 12 词助记词短语。

Olares ID 由本地名称和域名组成，例如alice2026@olares.com中，alice2026是本地名称，olares.com是域名。创建 Olares ID 的入口如下：

Step 1：安装 Olares

:::info 针对 Olares One 硬件 全新的 Olares One 设备出厂时处于未安装状态。在尝试激活之前，你必须先运行安装命令来部署 Olares。 :::

1. 以 root 身份运行安装命令：

   sudo olares-cli install

2. 当提示输入域名时，输入olares.com。

3. 当提示输入 Olares ID 时，输入你在 LarePass 应用中注册的 ID，例如alice2026。

4. 等待安装过程完成。终端会输出一个wizard URL和一个默认密码，请记录这些信息，供激活步骤使用。

   示例：

   • Wizard URL：本地网关地址，例如http://192.168.31.127:30180。
   • 密码：Olares 的默认登录密码。

从仓库源码结构看，install是 Olares CLI 中唯一的“系统层”命令之一（cli/README.md 将其与uninstall、upgrade、start、wizard等并列），负责把 Olares OS 部署到宿主机；对于通过 npm 渠道安装的独立 CLI，install由 Node 封装脚本处理（npm install -g同名版本后再执行olares-cli skills install，见 cli/npm/scripts/install-wizard.js）。

Step 2：准备 CLI 工具

根据你的 Olares 版本确定 CLI 的准备步骤。

1. 运行以下命令检查当前 Olares 版本：

   sudo olares-cli --version

2. 查看输出中的版本号，并根据版本选择对应的方法。

v1.12.6 及更高版本

v1.12.6 及更高版本的系统自带 CLI，且已内置激活功能，无需额外下载。直接进入 Step 3 即可。

v1.12.5 及更早版本

:::warning 请使用独立 CLI v1.12.5 及更早版本系统自带的olares-cli没有激活功能。你必须下载独立的 daily build CLI 来执行激活。使用该工具时请注意以下要求：

• 不要覆盖系统文件：系统内置的olares-cli、olaresd与集群版本之间存在严格的版本对应关系。因此，切勿把下载的独立 CLI 移动或复制去覆盖系统/usr/bin/olares-cli文件，否则会破坏这条版本链，影响未来的系统升级。
• 执行路径差异：对下载到当前目录的独立版本，请用./olares-cli执行；不要直接运行olares-cli，因为那会执行系统内置版本（缺少激活功能）。 :::

1. 下载独立的 Olares CLI 包：

   curl -sSOL https://cdn.olares.com/common/olares-cli-amd64.8cbdc32.tar.gz

2. 解压下载的文件：

   tar xzf olares-cli-amd64.8cbdc32.tar.gz

3. 为解压出的二进制文件添加可执行权限：

   chmod +x olares-cli

需要理解的是：wizard activate/wizard frp是 Go 二进制中wizard命令组的两个子命令（见 cli/cmd/ctl/wizard/root.go）。在 v1.12.5 及更早版本的系统二进制中不存在该命令组，因此才需要独立 daily build。版本检查通过olares-cli --version输出完成——npm 安装脚本正是解析这一输出（version <token>）来判断系统二进制是正式版（如1.12.7、1.12.8-rc1，予以保留）还是开发版（如0.0.0-development，予以替换）的（cli/npm/scripts/install-wizard.js）。

Step 3：获取 FRP 主机列表

找到一个可用的 FRP 主机，以启用设备的远程访问。

1. 根据你的 Olares 版本运行以下命令，将{olares-id}替换为你的 Olares ID：

   olares-cli wizard frp {olares-id}

   示例：

   olares-cli wizard frp alice2026@olares.com

   ./olares-cli wizard frp {olares-id}

   示例：

   ./olares-cli wizard frp alice2026@olares.com

2. 从输出列表中选择一个主机地址并记录下来，供激活步骤使用。例如bb.hongkong.frp.olares.com。

命令背后的实现：FRP 注册表查询

wizard frp命令是对 Olares 公共隧道（FRP）服务器注册表的无需认证查询，与激活向导“选择隧道”步骤在用户完成绑定之前调用的接口一致（cli/cmd/ctl/wizard/frp.go）。其底层实现要点（见 cli/pkg/wizard/frp.go）：

• 端点自动选择：根据 Olares ID 后缀自动选择 API 环境——以olares.cn结尾的 ID 查询https://api.olares.cn/frp，其余一律查询https://api.olares.com/frp；也可用--env=cn|en手动覆盖。
• 请求方式：向<base>/v2/servers发送POST，请求体为{"name": "<olaresId>"}，返回形如[{region, name: {"en-US":..., "zh-CN":...}, machine: [{host}]}]的服务器列表。
• 输出格式：默认以表格输出REGION / NAME / HOST三列，每行展示该区域下全部可达主机（多个主机用逗号分隔）；--output=json可输出完整原始响应；--lang（如en-US、zh-CN）用于渲染NAME列的多语言名称。若列表为空则输出no FRP servers。
• 超时与重试：请求使用默认 10 秒超时；如果 FRP 主机地址在激活阶段不可用，激活状态机会自动重试（见下节）。

Step 4：激活 Olares

运行激活命令来配置并加固你的设备。该过程会将你的 Olares ID 绑定到设备，并配置网络隧道和凭证。

1. 根据以下必填参数准备你的激活命令：

   参数	说明
   olares-id	你在 LarePass 中创建的 Olares ID，例如alice2026@olares.com。
   mnemonic	你的 Olares ID 对应的 12 词助记词短语。
   password	Step 1 中获取的 Olares 默认登录密码。
   reset-password	用来替换默认密码的新登录密码。
   authurl	Step 1 中获取的 Wizard URL。
   vault	Step 1 中获取的 Wizard URL，后面追加/server。
   bfl	Step 1 中获取的 Wizard URL。
   host	Step 3 中选择的 FRP 主机地址。
   enable-tunnel	设置为true以启用隧道模式。

2. 根据你的 Olares 版本，将以下命令中的占位符替换为你的实际值，然后运行：

   sudo olares-cli wizard activate {olares-id} \ --mnemonic "{mnemonic}" \ --password="{password}" \ --reset-password="{reset-password}" \ --authurl={authurl} \ --vault={vault} \ --bfl={bfl} \ --host={host} \ --enable-tunnel=true

   sudo ./olares-cli wizard activate {olares-id} \ --mnemonic "{mnemonic}" \ --password="{password}" \ --reset-password="{reset-password}" \ --authurl={authurl} \ --vault={vault} \ --bfl={bfl} \ --host={host} \ --enable-tunnel=true

   完整示例：

   假设 Olares ID 为alice2026@olares.com，Wizard URL 为http://192.168.31.127:30180，选定的 FRP 主机为bb.hongkong.frp.olares.com：

   sudo olares-cli wizard activate alice2026@olares.com \ --mnemonic "abcdef abcdef abcdef abcdef abcdef abcdef abcdef abcdef abcdef abcdef abcdef abcdef" \ --password="b8Ln6qbz" \ --reset-password="Abw1234@" \ --authurl=http://192.168.31.127:30180 \ --vault=http://192.168.31.127:30180/server \ --bfl=http://192.168.31.127:30180 \ --host=bb.hongkong.frp.olares.com \ --enable-tunnel=true

3. 等待终端显示激活成功完成的消息。

命令背后的实现：参数默认值与校验

wizard activate命令在 cli/cmd/ctl/wizard/activate.go 中定义，源码揭示了文档未列出的参数默认值与校验规则：

• 参数默认值（AddFlags中定义）：
  • --bfl：默认http://127.0.0.1:30180
  • --vault：默认http://127.0.0.1:30180（注释中的参考端口为 30181）
  • --authurl：默认空，为空时自动推导
  • --location：默认Asia/Shanghai（时区）
  • --language：默认en-US（系统语言）
  • --enable-tunnel：默认false
  • --jws：FRP JWS token，仅隧道启用时使用
• 必填校验（Validate）：olares-id、password、mnemonic、reset-password四项缺一不可，任一缺失都会直接报错退出。
• ID 解析：命令接受user@example.com形式的位置参数；若 ID 包含@，会自动截取@前的部分作为localName使用。

激活流程：绑定 + 状态机

从源码看，activate的执行分为两大阶段（对应 activate.go 的Run方法）：

第一阶段：用户绑定（Vault 激活）。调用 cli/pkg/wizard/auth.go 的UserBindTerminus，用助记词初始化全局存储后依次完成：对 Authelia 后端执行首因子认证（auth.FirstFactor，因激活阶段尚无 MFA seed，强制NeedTwoFactor=false）；发起 SSI 类型、Signup 目的的认证请求；用globalUserStore.SignJWS对{name, did, domain, time}签名生成 JWS；最后调用app.Signup完成注册并返回 access token。本地持久化由 cli/pkg/wizard/storage.go 的DirKVStorage承担，状态以 JSON 形式存放在~/.olares/<did>/目录下（权限 0700），同一 did 下的激活状态因此可跨命令复用。

第二阶段：系统激活状态机。绑定成功后，cli/pkg/wizard/wizard.go 的RunWizard启动一个轮询式状态机（对齐 Web 端ActivateWizard.vue的实现）：

• 每2 秒（PollInterval）向GET {bfl}/bfl/info/v1/olares-info查询wizardStatus，最多连续失败10 次（MaxRetries）后终止。
• 状态机按状态流转：wait_activate_vault/vault_activating/system_activating/network_activating/wait_activate_network为等待状态；wait_activate_system时向POST {bfl}/bfl/settings/v1alpha1/activate提交系统配置（时区、语言、以及启用隧道时的 FRPhost/jws）；wait_reset_password时执行密码重置（先登录获取 token，再调用ResetPassword）；到达completed即成功退出；vault_activate_failed/system_activate_failed/network_activate_failed视为失败并报错。
• 登录重置等环节底层使用 SRP 安全远程密码协议（见 cli/pkg/wizard/srp.go，支持 3072/4096/6144/8192 位组）；若服务端要求二次因子，cli/pkg/wizard/login_terminus.go 会从已保存的 MFA seed 本地计算 TOTP 自动完成验证。

下一步

激活成功后，你现在可以使用你的 Olares ID 和reset-password中指定的登录密码登录 Olares。

延伸阅读

• 创建 Olares ID：在 LarePass 中创建并管理你的 Olares ID。
• Olares CLI 概览：了解 olares-cli 的主机、用户与集群内三种运行模式，以及如何用它驱动 AI Agent。

• 云原生
• 后端
• 运维