# kiosk-client

**Repository Path**: c-java-father/kiosk-client

## Basic Information

- **Project Name**: kiosk-client
- **Description**: go wails 全屏
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-03
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KIOSK Desktop Client

基于 Wails v2 开发的全屏桌面客户端，WebView 直接加载 Go 后端地址 `http://127.0.0.1:3000`。

## 功能

- **全屏锁屏模式**：Frameless + Fullscreen + AlwaysOnTop，不可调整大小
- **退出密码验证**：关闭窗口 / 使用退出快捷键时需要输入密码
- **快捷键**：刷新页面（Ctrl+Shift+R）、退出客户端（Ctrl+Shift+Q）
- **外部 WebView**：直接加载后端地址，无需前端打包
- **配置外置**：所有配置集中在 `config.yaml`

## 项目结构

```
kiosk-client/
├── main.go              # 入口，Wails 窗口配置
├── app.go               # 应用逻辑，配置加载
├── config.yaml          # 配置文件（WebUrl、快捷键、密码）
├── wails.json           # Wails 项目配置
├── go.mod / go.sum      # Go 依赖
├── build.sh             # 构建脚本
├── curl.sh              # 运行管理脚本（start/stop/restart）
├── kiosk-client.service  # systemd 服务文件
├── kiosk-client.desktop  # 桌面入口文件
├── build/               # 构建资源（图标等）
└── README.md
```

## 配置文件

`config.yaml`：

```yaml
webUrl: "http://127.0.0.1:8080"   # 后端地址
exitHotkey: "Ctrl+Shift+Q"         # 退出快捷键
refreshHotkey: "Ctrl+Shift+R"      # 刷新快捷键
exitPassword: "rms6@2026"          # 退出密码
```

> 外部 config.yaml 优先于内嵌配置，部署时只需修改 config.yaml 即可。

## 构建

```bash
# 开发构建（当前平台）
./build.sh dev

# Linux (amd64)
./build.sh linux

# Windows
./build.sh windows

# macOS
./build.sh mac
```

## 部署（Linux）

```bash
# 1. 将 bin/ 目录拷贝到目标机器
scp -r bin/ user@server:/home/gst/kiosk-client/

# 2. 安装 systemd 服务
sudo cp kiosk-client.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable kiosk-client
sudo systemctl start kiosk-client

# 3. 管理
./curl.sh start    # 启动
./curl.sh stop     # 停止
./curl.sh restart  # 重启
./curl.sh status   # 状态
```

## 依赖

- Go 1.25+
- Wails v2.12+
- Linux: WebKitGTK
- Windows: WebView2
- macOS: WebKit

go install github.com/wailsapp/wails/v2/cmd/wails\@v2.12.0
go env GOPATH
配置环境变量libwebkit2gtk-4.1-dev

wget <https://go.dev/dl/go1.26.4.linux-arm64.tar.gz>
tar -C /usr/local -xzvf go1.26.4.linux-arm64.tar.gz
export PATH=$PATH:/usr/local/go/bin
echo "PATH=$PATH:/usr/local/go/bin" >> /etc/profile

sudo apt update
sudo apt install -y gcc build-essential pkg-config          # 基础编译工具
sudo apt install -y libgtk-3-dev                           # GTK3
sudo apt install -y libwebkit2gtk-4.0-dev                  # WebKit2（用 4.0 版本，已废弃但仍可用）

# 或 Ubuntu 22.04+/Debian 12+ 用：

apt update && sudo apt full-upgrade -y
apt install --only-upgrade libnghttp2-14 libsqlite3-0

apt install -y --fix-broken && sudo apt install -y gcc build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev

# 开启模块模式

go env -w GO111MODULE=on

# 设置七牛云国内代理，失败自动直连源站

go env -w GOPROXY=<https://goproxy.cn,direct>

# 可选：关闭校验库（部分网络环境进一步提升成功率）

go env -w GOSUMDB=off
go install github.com/wailsapp/wails/v2/cmd/wails\@v2.12.0

go version          # go version go1.22.5 linux/arm64
wails doctor        # 检查环境是否就绪，缺少什么
pkg-config --cflags gtk+-3.0 webkit2gtk-4.0   # 确认 GTK/WebKit 头文件可用
如果 pkg-config 报错找不到 webkit2gtk-4.0，换成 webkit2gtk-4.1 试试。然后就可以 bash build.sh linux-arm64 了

\#音频
apt install -y gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \
gstreamer1.0-alsa gstreamer1.0-pulseaudio gstreamer1.0-libav \
pipewire-pulse wireplumber

# TTS 语音合成（speechSynthesis 依赖）

sudo apt install -y speech-dispatcher speech-dispatcher-espeak-ng espeak-ng


# GStreamer 完整多媒体支持（Audio/MP3 依赖）

sudo apt install -y gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \
gstreamer1.0-alsa gstreamer1.0-pulseaudio gstreamer1.0-libav

# 确保 speech-dispatcher 运行

systemctl --user enable speech-dispatcher

# 2. 编译

go env GOPATH
配置环境变量
sed -i 's/\r$//' build.sh && chmod +x build.sh
sed -i 's/\r$//' curl.sh && chmod +x curl.sh
bash build.sh linux-arm64

cp kiosk-client.desktop /home/double/.local/share/applications/

装完后可以直接从应用菜单搜索"KIOSK"启动




一、先补齐 RK3588 多媒体底层依赖（必须先装）
# 1. 安装Mali GPU、WebKit、GStreamer MPP硬解插件
sudo apt update
sudo apt install -y mesa-utils libgl1-mesa-dri rockchip-multimedia-config gstreamer1.0-rockchip
sudo apt install -y libwebkit2gtk-4.1-dev libgtk-3-dev gstreamer1.0-plugins-good gstreamer1.0-plugins-bad
# 2. 初始化瑞芯多媒体硬件环境
sudo rockchip-multimedia-config
# 3. 校验GPU驱动正常
glmark2-es2
# 正常输出Mali-G610，无报错=GPU驱动就绪
ls /dev/dri/ # 看到card0、renderD128代表DRM显卡正常
dmesg | grep -i mali # 无failed代表GPU固件加载成功

二、运行 Wails 的关键环境变量（开启 GPU 渲染 + MPP 视频硬解）
1. 核心加速环境变量（启动 Wails 前必须 export）
# 1. 强制WebKit使用EGL/GLES硬件渲染（Mali GPU）
export GDK_BACKEND=wayland
export GDK_GL=gles
export LIBGL_ALWAYS_EGL=1
export MESA_GL_VERSION_OVERRIDE=3.2
# 2. 开启WebKit硬件合成、WebGL、视频硬解
export WEBKIT_DISABLE_COMPOSITING_THREAD=0
export WEBKIT_GL_CONTEXT_THREAD=1
export WEBKIT_ENABLE_MEDIA_HW_DECODING=1
# 3. GStreamer绑定RK MPP硬件解码器（视频硬解核心）
export GST_PLUGIN_PATH=/usr/lib/aarch64-linux-gnu/gstreamer1.0/plugins/rockchip
export GST_MPP_DEC_ENABLE=1
export GST_MPP_DRM_DISPLAY=1
# 4. 关闭软件渲染兜底，强制GPU
export LIBGL_ALWAYS_SOFTWARE=0
# 5. Wayland会话基础环境（double桌面登录自带）
export XDG_RUNTIME_DIR=/run/user/$(id -u)
export DISPLAY=:0

2. 一键启动 Wails 脚本示例（wails_run.sh）
#!/bin/bash
# 清空旧webkit缓存，避免加速冲突
rm -rf ~/.cache/wails ~/.local/share/webkit2gtk-4.1
# 加载全部GPU硬解环境变量
export GDK_BACKEND=wayland
export GDK_GL=gles
export LIBGL_ALWAYS_EGL=1
export MESA_GL_VERSION_OVERRIDE=3.2
export WEBKIT_ENABLE_MEDIA_HW_DECODING=1
export GST_PLUGIN_PATH=/usr/lib/aarch64-linux-gnu/gstreamer1.0/plugins/rockchip
export GST_MPP_DEC_ENABLE=1
export LIBGL_ALWAYS_SOFTWARE=0
export XDG_RUNTIME_DIR=/run/user/$(id -u)
# 延时等待桌面GPU初始化
sleep 2
# 启动你的wails二进制程序
/home/double/wails_app

授权：chmod +x wails_run.sh

三、Web 前端代码适配（让视频走硬件解码）
HTML 视频标签必须加硬件解码标识，否则 WebKit 自动走软解：
<!-- 开启硬件解码播放 -->
<video autoplay muted playsinline disablepictureinpicture>
  <source src="rtsp/hls/flv视频地址" type="video/mp4">
</video>

JS 关闭多余渲染消耗：
// 关闭多余动画，减轻GPU负载
document.body.style.animation = "none";
document.body.style.transition = "none";

四、开机自启自动带 GPU 加速（适配你 double 自动登录）
方案 1：autostart 桌面自启（登录后执行）
su - double
mkdir -p ~/.config/autostart
nano ~/.config/autostart/wails-gpu.desktop

[Desktop Entry]
Type=Application
Name=Wails GPU加速启动
Exec=/bin/bash -c "sleep 3 && /home/double/wails_run.sh >> /home/double/wails_gpu.log 2>&1"
X-GNOME-Autostart-enabled=true

方案 2：用户级 systemd 服务（带日志、崩溃重启）
su - double
mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/wails-gpu.service

[Unit]
Description=Wails GPU硬件加速服务
After=graphical-session.target gnome-shell.service

[Service]
Type=simple
Environment="GDK_BACKEND=wayland"
Environment="GDK_GL=gles"
Environment="LIBGL_ALWAYS_EGL=1"
Environment="WEBKIT_ENABLE_MEDIA_HW_DECODING=1"
Environment="GST_MPP_DEC_ENABLE=1"
WorkingDirectory=/home/double
ExecStart=/bin/bash -c "sleep 3 && /home/double/wails_run.sh"
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable wails-gpu
systemctl --user start wails-gpu
# 实时日志查看加速是否生效
journalctl --user -u wails-gpu -f


五、验证是否真正开启 GPU + 视频硬解
1. 验证 GPU 渲染（Mali）
# 查看WebKit进程GL渲染调用
ps aux | grep webkit2gtk
# 查看DRM/GPU占用
top -H | grep mali
# 查看显卡负载
glxinfo | grep "OpenGL renderer"
# 输出 Mali-G610 代表GPU渲染生效

2. 验证 MPP 视频硬解（VPU）
播放视频时执行：
# 查看RK硬解码进程
ps aux | grep mpp
# 查看VPU硬件占用
cat /proc/rk_vpu/stat

出现解码线程、VPU 占用上升 = 硬解成功，CPU 占用会大幅下降（正常 10% 以内）。


六、常见坑 & 修复（RK3588 专属）
报错 mpp_platform client driver not ready
原因：Wails 启动太早，MPP 驱动未初始化；解决：脚本增加sleep 3~5延时。
WebKit 依旧软解 4K 视频，CPU 满载
缺失gstreamer1.0-rockchip插件；
未设置WEBKIT_ENABLE_MEDIA_HW_DECODING=1；
HTML video 标签缺少playsinline。
GPU 渲染失败、界面卡顿、花屏
切换 Wayland 后端：export GDK_BACKEND=wayland，不要用 X11；
关闭软件渲染：LIBGL_ALWAYS_SOFTWARE=0。
和 Chromium 的 chrome_gpu.sh 冲突
WebKitGTK 与 Chromium 两套独立渲染，互不干扰；但同时大量 4K 视频会耗尽 VPU 硬解通道，建议控制并发路数。
七、和你现有业务搭配总结
startall.service(root 系统服务)：后台流媒体、后端服务；
double 自动登录→autostart/wails 用户服务：带完整 GPU 环境变量启动 Wails；
chrome_gpu.sh：独立 Chromium 大屏浏览器（单独一套 GPU 参数，和 Wails 隔离）；
全部硬件加速依靠环境变量 + RK MPP GStreamer 插件实现，无需修改 Wails 编译。