开发指南

项目概述¶

One-KVM 是使用 Rust 开发的轻量级 IP-KVM 服务，前端使用 Vue 3、TypeScript 和 Vite。后端通过 rust-embed 嵌入 web/dist；也可以在运行时用 ONE_KVM_FRONTEND_DIR 指向外部前端目录。

本地开发与编译¶

在项目根目录执行：

# 安装前端依赖并构建静态资源
cd web
npm install
npm run build

# 返回项目根目录，编译当前主机架构
cd ..
cargo build

前端开发服务器和后端分别启动时，可以使用：

cd web
npm run dev

# 另一个终端，在项目根目录运行后端
cargo run -- --log-level debug

运行测试：

cargo test
cd web && npm run build

cargo build 默认启用 desktop feature。Windows 构建需要预先安装 vcpkg 依赖；脚本会检查 VCPKG_ROOT、VCPKG_INSTALLED_DIR 和 x64-windows-static triplet：

# 在 Windows PowerShell 中，从项目根目录执行
.\build\windows\build.ps1
.\build\windows\build.ps1 -Configuration release -Package

脚本默认目标为 x86_64-pc-windows-msvc，也可以用 -Target、-Triplet、-NoDefaultFeatures 和 -Features 覆盖构建参数。

多架构构建¶

多架构脚本使用 cross 和 Docker。首次使用前安装 cross，并确保 Docker 可用：

1	`cargo install cross`

build-images.sh 支持以下目标：

./build/build-images.sh              # 全部：x86_64、arm64、armv7
./build/build-images.sh x86_64       # x86_64-unknown-linux-gnu
./build/build-images.sh arm64        # aarch64-unknown-linux-gnu
./build/build-images.sh armv7        # armv7-unknown-linux-gnueabihf
./build/build-images.sh --help

脚本生成的二进制位于 target/<rust-target>/release/one-kvm。在中国网络环境可以启用镜像：

CHINAMIRRO=1 ./build/build-images.sh arm64

DEB 包与 Docker 镜像¶

package-deb.sh 只负责打包已经生成的二进制文件；不带参数时打包全部架构，也可以指定 amd64、arm64 或 armhf：

./build/build-images.sh
./build/package-deb.sh             # target/debian/*.deb
./build/package-deb.sh arm64

Docker 镜像同样默认使用已编译的二进制。单架构镜像可加载到本机，多架构镜像需要推送到仓库：

# 当前平台，加载到本地 Docker
./build/package-docker.sh --load

# 完整版镜像（包含 gostc 和 easytier）
./build/package-docker.sh --variant full --platform linux/arm64 --load

# 多架构推送并生成统一 manifest
./build/package-docker.sh \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  --registry docker.io/用户名 --push

常用选项：--platform（支持 linux/amd64、linux/arm64、linux/arm/v7，逗号分隔）、--registry、--image-name、--tag、--variant minimal|full、--full、--push、--load 和 --build。其中 --build 会在打包前用 cross 构建二进制；--load 只能用于单一平台。

命令行参数¶

1
2
3

one-kvm [OPTIONS]
one-kvm user set-password
one-kvm user disable-totp

主要选项如下：

选项	作用
`-a, --address ADDRESS`	覆盖监听地址
`-p, --port PORT`（别名 `--http-port`）	覆盖 HTTP 端口
`--https-port PORT`	覆盖 HTTPS 端口
`--enable-https`	启用 HTTPS；未指定证书时在数据目录 `certs/` 中生成自签名证书
`--ssl-cert FILE`、`--ssl-key FILE`	指定 PEM 证书和私钥，必须同时提供
`-d, --data-dir DIR`	覆盖数据目录
`-l, --log-level LEVEL`	日志级别：`error`、`warn`、`info`、`debug`、`trace`

应用运行时环境变量¶

变量名	作用与默认值
`ONE_KVM_DATA_DIR`	默认数据目录。`-d/--data-dir` 优先；Linux 默认 `/etc/one-kvm`，Windows 默认程序目录下的 `one-kvm`。
`RUST_LOG`	tracing 过滤器；设置后优先于 `--log-level`，例如 `one_kvm=debug,tower_http=debug`。
`ONE_KVM_FFMPEG_LOG`	FFmpeg 日志等级；未设置或无效时为 `error`。支持数字及 `quiet`、`panic`、`fatal`、`error`、`warn`、`info`、`verbose`、`debug`、`trace`。
`ONE_KVM_WEBRTC_MDNS_MODE`	WebRTC mDNS：`disabled/off/false/0`、`query/query_only` 或 `gather/query_and_gather/on/true/1`；默认 `query`。
`ONE_KVM_FRONTEND_DIR`	外部前端静态资源目录；不可访问时回退到内嵌的 `web/dist`。
`ONE_KVM_UPDATE_BASE_URL`	在线升级地址；默认 `https://update.one-kvm.cn`。
`ONE_KVM_UPDATE_CURRENT_VERSION`	覆盖升级比较使用的当前版本，主要用于测试或特殊打包。
`ONE_KVM_CUA_API_KEY`	Computer Use Agent 的 API Key，优先于 `OPENAI_API_KEY`。
`OPENAI_API_KEY`	Computer Use Agent 的兼容 API Key（兼容旧配置）。
`ONE_KVM_CUA_BASE_URL`	Computer Use Agent 接口地址，优先于 `ONE_KVM_OPENAI_BASE_URL`。必须是包含 `/responses` 或 `/chat/completions` 的完整 `http(s)` URL。
`ONE_KVM_OPENAI_BASE_URL`	Computer Use Agent 的兼容接口地址（兼容旧配置）。
`ONE_KVM_V4L2M2M_ALLOW`	晶晨平台设置为非空且不为 `0` 时允许 V4L2 M2M 探测；默认跳过。
`ONE_KVM_RKMPP_DMABUF`	设置为 `0` 时禁用 RKMPP DMA 路径；默认启用。
`ONE_KVM_RKMPP_MJPEG_DMABUF`	设置为 `1` 时允许 MJPEG 使用 RKMPP DMA；默认关闭。
`RUSTDESK_HWCODEC_NVENC_GPU`	指定 NVENC GPU 编号；未设置或解析失败时为 `-1`。
`ONE_KVM_TTYD_PATH`	Windows 下覆盖 ttyd 可执行文件路径。

Docker 入口脚本环境变量¶

build/init.sh 会把下列变量转换为 one-kvm 启动参数：

变量名	作用与默认值
`DATA_DIR`	容器数据目录，优先于兼容变量 `ONE_KVM_DATA_DIR`；默认 `/etc/one-kvm`。
`ENABLE_HTTPS`	值为 `true` 时追加 `--enable-https`，默认关闭。
`BIND_ADDRESS`	追加 `-a` 覆盖监听地址。
`HTTP_PORT`	追加 `-p` 覆盖 HTTP 端口。
`HTTPS_PORT`	追加 `--https-port` 覆盖 HTTPS 端口。
`VERBOSE`	值为 `1`、`2`、`3` 时，入口脚本分别追加 `-v`、`-vv`、`-vvv`。当前后端 CLI 的正式日志选项是 `-l/--log-level`，容器中建议使用 `RUST_LOG` 或直接调整入口脚本。
`LIBVA_DRIVER_NAME`	指定 VA-API 驱动（如 `iHD`、`i965`）；设置后跳过自动探测。
`LIBVA_DEVICE`	指定 VA-API 探测的 DRM render 节点；未设置时扫描 `/dev/dri/renderD*`。

构建环境变量¶

变量名	作用与默认值
`CHINAMIRRO`	`1`、`true`、`yes` 或 `on` 时启用 Rust、Debian 和 GitHub 镜像。
`GH_PROXY`	中国网络环境下 GitHub 资源的代理前缀；未设置时脚本默认使用 `https://ghfast.top/`。
`DEBIAN_IMAGE`	覆盖交叉编译基础镜像；镜像默认值为 `dockerproxy.net/library/debian:12`（Dockerfile 默认 `debian:12`）。
`CROSS_BUILD_OPTS`	传给 `cross` 的额外构建选项。
`ONE_KVM_LIBS_PATH`	覆盖桌面/服务器端 FFmpeg 等本地库的搜索路径。
`FFMPEG_STATIC`	设置为 `1` 时启用 FFmpeg 静态链接；默认按动态库处理。
`VCPKG_ROOT` / `VCPKG_INSTALLED_DIR`	Windows 构建脚本使用的 vcpkg 根目录和已安装目录。