WebUI Configuration Guide Chinese

🌐 AionUi WebUI 配置教程

本教程详细介绍如何在 WebUI 模式下配置和使用 AionUi，实现基于浏览器的访问和远程连接本地 AI 助手。

English | 简体中文

---

🎯 WebUI 模式简介

WebUI 模式让您通过浏览器访问 AionUi，支持任意浏览器、局域网访问、跨网络远程访问和服务器部署。

---

🎯 使用场景（点击跳转）

根据您的需求，选择对应的使用场景：

• 🌐 跨网络访问（推荐）：步骤 1 → 步骤 2 → 步骤 3（Tailscale）
• 📱 局域网访问：步骤 1 → 步骤 2 → 步骤 3（同一网络）
• 🏠 仅本地使用：步骤 1 → 步骤 2
• 🖥️ 服务器部署：步骤 1 → 步骤 2 → 步骤 4

---

📋 快速命令参考

💡 推荐：优先使用界面方式启动 WebUI（见下方"快速开始"部分），更简单直观。

如果您需要使用命令行，这里是各平台启动 WebUI 的常用命令：

平台	本地访问	网络访问（局域网） ⭐
Windows	AionUi.exe --webui	AionUi.exe --webui --remote
macOS	/Applications/AionUi.app/Contents/MacOS/AionUi --webui	/Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote
Linux	AionUi --webui	AionUi --webui --remote
Android	AionUi --no-sandbox --webui	AionUi --no-sandbox --webui --remote

提示：如果命令找不到，请使用完整路径（见下方各平台详细说明）。Linux root 用户和 Android 需要添加 --no-sandbox 参数。

---

---

🚀 快速开始

方式一：在界面中启动（推荐）⭐

1. 打开 AionUi 应用
2. 进入 WebUI 设置：点击左侧菜单中的 "WebUI" 选项
3. 启用 WebUI：
   • 打开 "启用 WebUI" 开关
   • 如需局域网访问，同时打开 "允许局域网访问" 开关
4. 查看访问地址：启动成功后，界面会显示访问地址和登录信息

💡 提示：界面操作更简单直观，推荐使用此方式启动 WebUI。

配置 Channels（可选）

在 WebUI 设置页面中，您还可以配置 Channels，将 AionUi 连接到 Telegram、Lark 等聊天平台：

1. 在 WebUI 设置页面中，向下滚动到 "Channels" 部分
2. 添加 Channel：
   • 点击 "添加 Channel" 或相应的配置按钮
   • 选择要连接的平台（如 Telegram、Lark 等）
   • 按照提示完成配置（通常需要提供 Bot Token 或 Webhook URL）
3. 使用 Channel：配置完成后，您可以通过对应的聊天平台与 AionUi 对话

💡 提示：Channels 配置是可选的，主要用于通过第三方聊天平台访问 AionUi。如果只需要通过浏览器访问，可以跳过此步骤。

---

方式二：命令行启动（备选方案）

如果您更喜欢使用命令行，可以在终端运行以下命令：

🪟 Windows

打开命令提示符或 PowerShell，运行：

AionUi.exe --webui

如需局域网访问：

AionUi.exe --webui --remote

如果命令找不到，使用完整路径：

"C:\Program Files\AionUi\AionUi.exe" --webui

🍎 macOS

打开终端，运行：

/Applications/AionUi.app/Contents/MacOS/AionUi --webui

如需局域网访问：

/Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote

🐧 Linux

桌面环境（非 root 用户）：

本地访问：

AionUi --webui

网络访问（局域网）：

AionUi --webui --remote

Root 用户：

如果使用 root 用户，需要添加 --no-sandbox 参数：

sudo AionUi --webui --no-sandbox
sudo AionUi --webui --remote --no-sandbox

其他启动方式：

• 使用完整路径：/usr/bin/AionUi --webui
• 使用 AppImage：./AionUi-*.AppImage --webui

---

📱 Android (Termux)

社区贡献：特别感谢 @Manamama 创建本指南！
原始教程：通过 Termux + Proot Ubuntu 在 Android 上运行 AionUi WebUI
相关问题：#217 - Android 支持讨论

⚠️ 重要提示：

• Electron 桌面模式在 Android 上不支持，仅支持 WebUI 模式
• 从 F-Droid 安装 Termux（Google Play 版本已过时）
• 要求：约 5 GB 可用存储空间，网络连接，Android 7.0+

步骤 1：安装 Termux 和 Proot

打开 Termux，执行：

pkg update -y
pkg install proot-distro -y
proot-distro install ubuntu
proot-distro login ubuntu

步骤 2：安装系统依赖

apt update
apt install -y wget libgtk-3-0 libnss3 libasound2 libgbm1 libxshmfence1 ca-certificates

步骤 3：下载并安装 AionUi

wget https://github.com/iOfficeAI/AionUi/releases/download/v1.5.2/AionUi_1.5.2_arm64.deb
apt install -y ./AionUi_*.deb
which AionUi

步骤 4：启动 AionUi

• 本地访问：AionUi --no-sandbox --webui
• 网络访问：AionUi --no-sandbox --webui --remote

💡 快速启动（从 Termux 主 shell）：

proot-distro login ubuntu -- bash -c "AionUi --no-sandbox --webui --remote"

步骤 5：访问 WebUI

在浏览器中打开 http://localhost:25808

📋 附加信息

预期警告（可安全忽略）：

[WARNING] Could not connect to session bus...
[ERROR] Failed to connect to the bus...
[WARNING] Multiple instances of the app detected...

这些错误与 D-Bus 和 X server 相关，WebUI 模式不需要这些。

性能提示：

• 使用轻量级浏览器（Chrome 或 Firefox Focus）
• 关闭后台应用释放 RAM
• 使用 WiFi 而非移动数据
• 保持设备充电

故障排除：

• 端口被占用：添加 --port 8080 标志
• 权限被拒绝：运行 chmod +x /opt/AionUi/aionui
• 内存不足：关闭其他应用
• 无法访问：检查 AionUi 是否运行，清除浏览器缓存

需要帮助？
查看完整详细教程或在 GitHub Issue #217 报告问题

---

第二步：访问 Web 界面

启动后，您会看到类似输出：

🚀 WebUI started / WebUI 已启动: http://localhost:25808

只需在浏览器中打开此 URL。应用程序启动时会自动打开默认浏览器。

---

第三步：首次登录

首次启动时，您会看到初始凭证：

========================================
  ✅ Default admin user created!
========================================
  
  Username: admin
  Password: [随机密码]
  
  🌐 Access URL: http://localhost:25808
  
========================================

重要：请立即复制密码 - 您需要它来登录！

---

🌐 跨网络远程

适用场景：不在同一网络也能访问（如：公司电脑访问家里服务器，或手机用流量访问）

通过配置跨网络远程访问，您可以从任何网络环境访问您的 AionUi 实例，无需配置路由器或公网 IP。

💡 推荐方案：可以使用 Tailscale 等远程软件实现跨网络访问。安装 Tailscale 后，在服务器和客户端设备登录同一账号，使用 Tailscale 分配的虚拟 IP（通常是 100.x.x.x:25808）即可访问。

---

📖 详细教程

如需完整的配置步骤和故障排除，请查看：

🌐 远程外网连接教程 →

---

🌍 局域网访问配置

适用场景：同一 WiFi/局域网内的设备访问（如：手机和电脑连同一个 WiFi）

步骤 1：启用局域网访问

方式一：在界面中启用（推荐）⭐

1. 打开 AionUi 应用
2. 进入 WebUI 设置页面
3. 打开 "启用 WebUI" 开关
4. 打开 "允许局域网访问" 开关

方式二：使用命令行（备选方案）

在启动命令中添加 --remote 标志：

• Windows: AionUi.exe --webui --remote
• macOS: /Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote
• Linux: AionUi --webui --remote（root 用户需添加 --no-sandbox）
• Android: AionUi --no-sandbox --webui --remote

步骤 2：获取访问地址

启动后，AionUi 会显示网络访问地址：

🚀 Network access / 网络访问: http://192.168.1.100:25808

💡 提示：如果未显示，Windows 运行 ipconfig，macOS/Linux 运行 ifconfig 查看 IP 地址。

步骤 3：从其他设备访问

在其他设备（手机、平板等）的浏览器中打开显示的地址，使用您的凭证登录即可。

⚠️ 注意：仅在受信任的网络上使用远程模式。

---

🔐 认证设置

默认凭证

AionUi 首次在 WebUI 模式下启动时，会自动创建默认管理员用户：

• 用户名：admin
• 密码：随机生成的 12 位密码（在控制台显示）

安全功能

• 速率限制：登录尝试受到速率限制（15 分钟内 5 次尝试）
• 密码哈希：使用 bcrypt 对密码进行哈希处理
• 会话令牌：使用 JWT 令牌进行安全会话管理
• Cookie 保护：使用 HttpOnly 和 SameSite Cookie 防止 CSRF 攻击

用户说明

⚠️ 重要：WebUI 目前仅支持单用户（admin）。多用户功能正在开发中。

---

🖥️ 服务器部署

适用场景：在服务器上 24/7 运行，支持远程访问和自动重启

🍎 macOS - LaunchAgent 后台运行

步骤 1：创建配置文件

创建 ~/Library/LaunchAgents/com.aionui.webui.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.aionui.webui</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Applications/AionUi.app/Contents/MacOS/AionUi</string>
    <string>--webui</string>
    <string>--remote</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

步骤 2：启动服务

launchctl load ~/Library/LaunchAgents/com.aionui.webui.plist
launchctl start com.aionui.webui

🐧 Linux - systemd（推荐）

步骤 1：创建服务文件

sudo nano /etc/systemd/system/aionui-webui.service

步骤 2：添加配置

[Unit]
Description=AionUi WebUI Service
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/usr/bin/AionUi --webui --remote
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

💡 提示：将 YOUR_USERNAME 和 /usr/bin/AionUi 替换为实际值。

步骤 3：启用并启动

sudo systemctl daemon-reload
sudo systemctl enable aionui-webui.service
sudo systemctl start aionui-webui.service
sudo systemctl status aionui-webui.service

常用管理命令：

• 查看日志：sudo journalctl -u aionui-webui.service -f
• 重启服务：sudo systemctl restart aionui-webui.service
• 停止服务：sudo systemctl stop aionui-webui.service

步骤 4：获取访问地址

查看日志中的访问地址，或运行：

sudo journalctl -u aionui-webui.service | grep "WebUI"

💡 自定义端口：在 [Service] 中添加 Environment="AIONUI_PORT=8080"，然后重启服务。

---

🔑 密码管理

在界面中管理密码（推荐）⭐

在 AionUi 应用界面中，您可以方便地管理 WebUI 密码：

1. 打开 AionUi 应用
2. 进入 WebUI 设置：点击左侧菜单中的 "WebUI" 选项
3. 查看密码：
   • 首次启动时，密码会以明文显示，可以直接复制
   • 复制后密码会自动隐藏为 ******
4. 重置密码：
   • 点击密码旁边的刷新图标 🔄
   • 会弹出设置新密码的对话框
   • 可以设置自定义密码，或生成随机密码
5. 修改密码：
   • 在设置新密码对话框中输入新密码并确认
   • 密码设置成功后，之前的会话令牌会失效，需要重新登录

💡 提示：界面操作更简单直观，推荐使用此方式管理密码。

使用命令行重置密码（备选方案）

如果您更喜欢使用命令行，也可以在终端运行 --resetpass 命令：

各平台命令：

• Windows: AionUi.exe --resetpass 或 AionUi.exe --resetpass admin
• macOS: /Applications/AionUi.app/Contents/MacOS/AionUi --resetpass 或 /Applications/AionUi.app/Contents/MacOS/AionUi --resetpass admin
• Linux: AionUi --resetpass 或 AionUi --resetpass admin

提示：

• 如果命令找不到，请使用完整路径（参考上方"命令行启动方式"部分的路径）
• 目前仅支持 admin 用户，username 参数保留用于未来的多用户功能

运行 --resetpass 时会发生什么：

1. 连接到数据库
2. 找到指定的用户（默认为 admin，可通过参数指定）
3. 生成新的随机 12 位密码
4. 更新数据库中的密码哈希
5. 轮换 JWT 密钥（使所有先前的令牌无效）
6. 在终端显示新密码

运行 --resetpass 后：

1. 从终端复制新密码
2. 刷新浏览器（Cmd+R 或 Ctrl+R）
3. 您将被重定向到登录页面
4. 使用终端中显示的新密码登录

---

🛠️ 故障排除

端口已被占用

如果端口 25808 已被占用，AionUi 将自动尝试下一个可用端口。请检查控制台输出以了解实际端口号。

无法从浏览器访问

1. 检查应用程序是否成功启动

   • 在控制台中查找 "Server started on port XXXX" 消息

2. 尝试不同的浏览器

   • Chrome、Firefox、Safari 或 Edge

3. 清除浏览器缓存

   • 按 Ctrl+Shift+Delete（Windows/Linux）或 Cmd+Shift+Delete（macOS）

防火墙阻止访问

Windows:

# 允许通过 Windows 防火墙
netsh advfirewall firewall add rule name="AionUi WebUI" dir=in action=allow protocol=TCP localport=25808

Linux (UFW):

sudo ufw allow 25808/tcp

macOS:

• 转到 系统偏好设置 → 安全与隐私 → 防火墙 → 防火墙选项 → 添加 AionUi

找不到应用程序

查找应用程序位置：

Windows:

where AionUi.exe

macOS:

mdfind -name "AionUi.app"

Linux:

which AionUi
# 或
find /usr/bin -name "AionUi" 2>/dev/null

查看日志

Windows (PowerShell):

& "C:\Program Files\AionUi\AionUi.exe" --webui 2>&1 | Tee-Object -FilePath aionui.log

macOS/Linux:

AionUi --webui 2>&1 | tee aionui.log

---

📝 命令行选项总结

选项	描述
--webui	启动 WebUI 模式
--remote	允许远程网络访问
--webui --remote	组合两个标志
--port <端口>	指定端口号（默认 25808）
--webui-port <端口>	指定 WebUI 端口（等同于 --port）
--resetpass [用户名]	重置管理员密码（默认 admin，见上文）

---

⚙️ 环境变量和配置文件

环境变量

您可以使用环境变量来自定义 WebUI 行为：

端口配置：

# 设置端口（优先级高于配置文件）
export AIONUI_PORT=8080
# 或使用通用 PORT 变量
export PORT=8080

远程访问配置：

# 启用远程访问（无需 --remote 参数）
export AIONUI_ALLOW_REMOTE=true
# 或使用 AIONUI_REMOTE
export AIONUI_REMOTE=true
# 或通过 HOST 设置（设置为 0.0.0.0 等同于启用远程访问）
export AIONUI_HOST=0.0.0.0

配置优先级：

1. CLI 参数（--port、--remote） - 最高优先级
2. 环境变量（AIONUI_PORT、AIONUI_ALLOW_REMOTE）
3. 配置文件（webui.config.json）
4. 默认值（端口 25808，仅本地访问）

配置文件

从 v1.5.0+ 开始，您可以在配置文件中存储持久的 WebUI 设置：

配置文件位置：

平台	路径
Windows	%APPDATA%\AionUi\webui.config.json
macOS	~/Library/Application Support/AionUi/webui.config.json
Linux	~/.config/AionUi/webui.config.json

配置文件示例：

{
  "port": 8080,
  "allowRemote": true
}

使用配置文件：

• 创建或编辑上述路径的 webui.config.json 文件
• 设置 port 和 allowRemote 选项
• 重启 AionUi 后配置会自动生效
• CLI 参数和环境变量会覆盖配置文件中的设置

---

💡 最佳实践

用于开发

• 使用 --webui 标志进行快速测试
• 仅在本地网络上启用局域网访问
• 保持默认管理员密码安全

用于生产环境

• 使用 systemd/LaunchAgent 自动启动
• 设置防火墙规则以限制访问
• 使用 VPN 进行外部访问
• 定期更新密码
• 保持 AionUi 更新到最新版本

用于本地网络访问

• 确保所有设备在同一网络上
• 如果访问不起作用，请检查路由器设置
• 使用计算机的 IP 地址进行访问

---

🔗 相关资源

• 📖 快速开始指南 - 初始设置和配置
• ⚙️ 大模型配置 - 配置 AI 模型
• 🤖 多 Agent 设置 - 集成终端 AI 代理
• 🔌 MCP 配置 - Model Context Protocol 设置
• 🌐 远程外网连接教程 - 配置公网访问和 HTTPS
• ❓ 常见问题 - 常见问题和解决方案

---

🌟 功能特性

安全性

• HTTPS 就绪：可以部署在带有 SSL 的反向代理后面
• 会话管理：24 小时后自动会话超时
• 速率限制：防止暴力破解攻击
• CSRF 保护：内置跨站请求伪造保护

数据存储

• 本地 SQLite 数据库：所有数据存储在本地
• 无云存储：您的对话永远不会离开您的计算机
• 隐私优先：完全控制您的数据

性能

• 低资源使用：在大多数系统上高效运行
• WebSocket 实时：通过 WebSocket 实时更新
• 高效流式传输：优化的响应流式传输

---

祝您愉快地使用 AionUi WebUI 模式！ 🚀