基于 .NET 8 的 Web 后台管理与远程控制服务
本项目支持 Windows 和 Linux 操作系统。
本仓库新增 macOS 服务端适配，并在根路径的 Web 工作台支持手机浏览器与 PWA 安装。安装、功能范围和实机验证步骤请阅读 MACOS-H5.md。Mac 桌面代理需要在 Mac 上编译并授权。
配套 RemoteTool Android App 支持 Android 8.0 及以上，采用 Kotlin / Jetpack Compose 原生界面，通过本项目的服务端 API 管理电脑。
- 🖥️ 系统控制 - 实时监控 CPU、内存、磁盘、显卡等硬件信息，支持锁定、睡眠、休眠、关机等操作
- 📊 进程管理 - 查看和管理系统进程，支持按类型筛选和终止进程
- 🎮 远程控制 - 实时远程桌面控制，支持 H.264 编码，可调节分辨率和画质 🪟 Windows
- 💻 命令终端 - WebSocket 远程终端，支持 PowerShell/CMD 🪟 Windows，支持Shell 🐧 Linux
- 🐳 容器管理 - Docker 容器的启动、停止、删除和日志查看
- 📝 Compose 编辑 - Docker Compose 文件的在线编辑、验证和一键部署
- 📁 文件管理 - 远程文件浏览、上传、下载和删除
- ⏰ 任务调度 - Hangfire 的定时任务管理，自行添加任何任务 (内置qBittorrent管理、DDNS 等任务模板)
- 🔐 安全认证 - JWT 认证保护所有敏感操作
- 多设备管理：一个设备可保存多个 LAN、IPv6、VPN 或域名地址，校验设备身份，支持测速、手动切换通道和恢复上次连接。
- 系统监控：查看 CPU、内存、网络历史曲线及硬件温度、风扇转速；支持折叠卡片、电源操作和进程管理。传感器数据取决于电脑硬件和服务端支持。
- 远程桌面：H.264 硬件解码、横屏全屏、画质档位、直接触控与触控板、双指滚轮、缩放和平移，以及手机输入法；进入页面后手动连接。远程桌面主要支持 Windows。
- Codex / Hermes：浏览、搜索、新建及继续会话，流式回复、Markdown、工具进度、运行计时、图片和文件附件、问题回答、斜杠命令，以及可编辑的消息队列。可选择模型和支持的思考程度；Codex 还支持项目目录、快速模式、个人／团队工作空间切换和用量展示。需要在被管理的电脑配置相应 Agent。
- 更多管理工具：文件浏览与传输、图片／视频预览、Docker / Compose、命令终端、Hangfire 任务及执行日志，并提供应用更新检查。
从 GitHub Releases 下载 APK；安装后添加电脑服务的完整根地址并登录。更新请覆盖安装，以保留设备配置。构建及服务端接入说明见 app/README.md。
以下为用户提供的实际界面截图。
系统监控与远程桌面
Codex 会话列表与对话
Hermes 会话与更多工具
点击展开功能截图
实时监控系统硬件信息，一键执行电源操作。
查看所有运行中的进程，支持筛选和终止操作。
实时远程桌面，支持 H.264 视频流，低延迟高画质。
WebSocket 远程终端，支持 PowerShell 和 CMD。
管理 Docker 容器的完整生命周期。
在线编辑和部署 Docker Compose 项目。
远程浏览和管理服务器文件。
- 🪟 Windows 10/11 或 Windows Server
- 🐧 任何可运行 .NET 8 的 Linux 操作系统
- .NET 8 SDK/Runtime
- （可选，仅Windows）IIS + ASP.NET Core Hosting Bundle🪟 Windows
- 克隆仓库
git clone https://github.com/bighamx/RemoteTool.git
cd RemoteTool- 配置应用
# 复制示例配置文件
copy WebApplication\appsettings.example.json WebApplication\appsettings.json编辑 appsettings.json，配置必要的参数：
{
"Auth": {
"Username": "你的用户名",
"Password": "你的密码",
"JwtSecret": "至少32位的随机密钥"
}
}- 运行应用
cd WebApplication
dotnet run- 访问服务
- 单页工作台：
http://localhost:5104/#/。左侧导航切换总览、远程管理、任务、Codex、Hermes 时不刷新整页，例如终端/#/terminal、远程桌面/#/desktop、任务/#/jobs。 - 旧地址
/remote/index#tab=...、/hangfire、/agents/codex、/agents/hermes仍可作为书签访问，并会跳转到工作台地址。
Windows 上若 Docker Desktop 安装在交互用户目录，IIS 可能找不到 docker.exe。可在私有 appsettings.json 配置 RemoteControl:DockerPath 和 RemoteControl:DockerComposePath，指向服务账户可读取的 CLI 副本；未配置时优先查找 %ProgramData%\RemoteTool\tools。/api/docker/info 应返回服务端版本，连接失败会显示错误，不再把失败当作 0 个容器。FFmpeg 同样可通过 RemoteControl:FFmpegPath 指定。
| 配置项 | 说明 | 示例 |
|---|---|---|
Auth:Username |
登录用户名 | admin |
Auth:Password |
登录密码（必填） | YourSecurePassword |
Auth:JwtSecret |
JWT 签名密钥（必填，≥32位） | YourSecretKey... |
管理员在工作台 设置 → 身份验证（/#/identity）配置；现有用户名/密码登录仍可作为本地回退。OIDC 可添加多个提供方，分别填写 HTTPS Issuer、Client ID、Client Secret、scope 和允许邮箱。默认使用 OIDC Discovery；非标准 well-known 路径可填写 Discovery URL；没有 Discovery 的提供方可关闭该选项，明确配置 Auth URL、Token URL、Certificate/JWKS URL，以及可选的 UserInfo URL。手动配置同样使用公钥验证 ID Token，支持 JWKS JSON 或 PEM 证书及密钥刷新。所有提供方在服务端使用授权码 + PKCE，在提供方登记的精确回调地址是站点外部地址加 /access/callback，例如 https://remote.example.com/access/callback，不是提供方的授权入口。启用后登录页会显示对应按钮。提供方需在 ID Token 返回 email；仅当邮箱只在 UserInfo 时勾选该选项并配置对应 URL。
Cloudflare Access 也在该页单独启用，填写 Team 名称（不含 .cloudflareaccess.com）、该 Access 应用的 AUD Tag 和允许邮箱。RemoteTool 验证签名、Issuer、Audience、有效期和邮箱后建立本地会话。OIDC 与 Cloudflare Access 的允许邮箱分别配置，均为精确邮箱匹配；目前获准用户拥有 RemoteTool 管理员权限。
OIDC Client Secret 加密存放在私有数据目录 oidc/providers.json，加密密钥派生自私有 Auth:JwtSecret；请勿把该密钥或数据文件提交到 Git，也不要随意轮换 Auth:JwtSecret（轮换后须重新登记 Client Secret）。Cloudflare Access 配置位于同目录的 oidc/cloudflare-access.json，首次进入配置页面前仍兼容原有 appsettings.json 的单邮箱设置。两类设置保存后即时生效。生产环境必须使用 HTTPS 外部地址；反向代理需要正确转发原始 scheme/host。此功能只为网页实现，Android App 仍使用原有登录接口，不会自动完成第三方网页跳转。
安全注意：不要仅依赖登录页隐藏或邮箱白名单来保护源站。应在身份提供方配置允许的客户端与回调地址，并限制公网源站入口；移除允许邮箱或停用提供方会使其新签发的 RemoteTool 会话令牌在下一次请求时失效。原有密码登录及其令牌仍独立有效，退出或改密码不等于撤销所有旧令牌。
qBittorrent 设置
{
"QbSettings": {
"DefaultDockerUrl": "http://user:pass@host:port",
"DefaultHomeUrl": "http://user:pass@host:port"
}
}Cloudflare DDNS 设置
{
"CloudflareSettings": {
"ApiToken": "YOUR_API_TOKEN",
"ZoneId": "YOUR_ZONE_ID",
"RecordName": "your.domain.com",
"Proxied": false,
"Ttl": 1800
}
}远程控制提权代理
用于在 IIS/Session 0 环境下执行需要桌面交互的操作：
{
"RemoteControl": {
"ElevatedAgent": {
"UserName": "管理员用户名",
"Password": "管理员密码",
"Domain": "可选，域名"
}
}
}或使用环境变量：REMOTECONTROL_ELEVATEDAGENT_PASSWORD
# 开发模式
dotnet run --project WebApplication/WebApplication.csproj
# 发布后运行
dotnet publish -c Release -o publish
cd publish
WebApplication.exe
WebApplication是当前服务端项目和程序集的名称（AssemblyName未显式设置，跟随项目文件名）；项目历史名为ChuckieHelper.WebApi，旧版本部署里残留的同名 DLL 属于过往构建，可忽略。
服务端在首次启动（以及改名为 RemoteTool 后的首个新版本启动）会把数据目录定位到 %ProgramData%\RemoteTool：
| 内容 | 路径 |
|---|---|
| Codex 桥接配置/状态、会话恢复日志 | %ProgramData%\RemoteTool\codex-bridge |
| Hermes / Codex 会话附件 | %ProgramData%\RemoteTool\{hermes,codex}-attachments |
| Hermes 压缩任务记录 | %ProgramData%\RemoteTool\hermes-compactions |
| 多端共享的运行注册表 | %ProgramData%\RemoteTool\run-registry.json |
| 桌面代理日志 | %ProgramData%\RemoteTool\logs\desktop-agent-startup.log |
由 RemoteTool 旧版本（原名 ChuckieHelper）升级时，Services/RemoteToolDataMigration.cs 会把旧的 %ProgramData%\ChuckieHelper（以及当前运行用户 %LocalAppData%、临时目录下的同名目录）迁移到新位置。每个目标目录独立记录 data-migration.done，不同用户的数据迁移互不影响；同名文件冲突或文件被占用时保留原文件，并在后续启动重试，完成后才删除空的旧目录。迁移会重写指定 JSON 状态文件中以旧数据目录开头的路径，保留日志和消息文本。升级应先结束活跃任务并停止旧桥接、桌面代理，再启动新版本，避免旧进程继续写入旧目录。
Hermes API 密钥默认读取 %ProgramData%\RemoteTool\hermes\api-key.env，可通过 Hermes:KeyFile 或 HERMES_API_KEY_FILE 覆盖；该文件应只授权运行账户及 IIS 应用池读取。Hermes 自身的安装目录与 state.db 仍位于运行用户的 %LocalAppData%\hermes，IIS 部署必须通过 Hermes:HomeDirectory 明确指定桌面用户的 Hermes 目录，不能从密钥所在目录推断。
解决方案中的类库与测试项目分别为 RemoteTool.Lib、RemoteTool.Lib.Tests，传感器程序为 tools/RemoteTool.SensorHost，服务端代码命名空间为 RemoteTool.WebApi。为兼容已有 Hangfire 任务，仅任务类型的 ChuckieHelper.WebApi.Jobs 命名空间暂时保留，旧任务记录中的程序集名由类型解析器映射到当前程序集；设备 ID 的哈希前缀、桌面代理管道/计划任务名、Android 应用 ID/密钥别名和历史附件标记也保留，避免改名导致任务无法读取、重复代理或客户端凭据失效。
-
启用 IIS
- 打开「控制面板」→「程序」→「启用或关闭 Windows 功能」
- 勾选以下项目：
- ✅ Internet Information Services
- ✅ Web 管理工具 → IIS 管理控制台
- ✅ 万维网服务（保留 Windows 默认启用的角色服务即可）
- ✅ 万维网服务 → 应用程序开发功能 → WebSocket 协议（终端和远程输入功能需要）
本项目是 .NET 8 / ASP.NET Core 应用，不依赖传统的 ASP.NET 4.8、.NET Extensibility 4.8 或 ASP.NET 4.x 托管模块，无需为本项目启用这些组件。也不建议勾选“常见 HTTP 功能”下的全部项目，例如生产环境通常不应启用“目录浏览”。
-
安装 .NET 8 Hosting Bundle
- 下载 .NET 8 Hosting Bundle
- Hosting Bundle 会安装 .NET 运行时和 IIS 所需的 ASP.NET Core Module（ANCM）
- 请先启用 IIS，再安装 Hosting Bundle；如果安装顺序相反，请在启用 IIS 后重新运行安装程序并选择“修复”
- 安装完成后重启 IIS（或重启电脑）
dotnet publish WebApplication/WebApplication.csproj -c Release -o C:\inetpub\RemoteTool📁 发布后，将你的
appsettings.json复制到C:\inetpub\RemoteTool目录
- 打开「IIS 管理器」（运行
inetmgr） - 右键「应用程序池」→「添加应用程序池」
- 名称：
RemoteToolPool - .NET CLR 版本：
无托管代码 - 托管管道模式：
集成
- 名称：
- 点击「确定」创建
⚠️ 仅在需要远程控制功能时配置。LocalSystem 具有最高权限，请谨慎使用。
- 在「应用程序池」中找到
RemoteToolPool - 右键 →「高级设置」
- 找到「进程模型」→「标识」，点击右侧的
...按钮 - 选择「内置帐户」→ 下拉选择 LocalSystem
- 点击「确定」保存
- 在 IIS 管理器中，右键「网站」→「添加网站」
- 配置如下：
- 站点名称：
RemoteTool - 应用程序池：选择
RemoteToolPool - 物理路径：
C:\inetpub\RemoteTool - 绑定：
- 类型：
http（或https） - IP 地址：
全部未分配 - 端口：
5104（或你希望的端口）
- 类型：
- 站点名称：
- 点击「确定」创建
- 启动网站（右键网站 →「管理网站」→「启动」）
- 浏览器访问：
http://localhost:5104/ - 使用
appsettings.json中配置的账号密码登录
| 问题 | 解决方案 |
|---|---|
| 502.5 错误 | 检查 Hosting Bundle 是否正确安装，尝试重启 IIS |
| 500 错误 | 检查 appsettings.json 是否存在且格式正确 |
| 权限不足 | 确认应用程序池使用 LocalSystem 身份运行 |
| 端口被占用 | 更换端口或停止占用端口的服务 |
⚠️ 安全提示：appsettings.json包含敏感信息，请勿提交到公开仓库！
在 IIS/Session 0 环境下，远程控制功能需要桌面代理的支持才能和用户桌面进行交互。
桌面代理进程会被自动创建，创建桌面代理进程时，优先使用复制已有管理员令牌的方式，若无则依赖计划任务：
- 复制已有管理员令牌：在当前交互会话中查找已存在的高完整性进程（如用户曾以管理员运行过任务管理器等），复制其令牌并用于启动代理，无需配置密码，即时生效。
- 计划任务：若未找到高完整性令牌，且已配置
RemoteControl:ElevatedAgent（管理员用户名与密码），应用启动时会自动创建“登录时以最高权限运行”的计划任务，用户注销并重新登录后，桌面代理将以管理员身份自动启动。 - 代理通过命名管道与 WebApi 通信，执行键鼠输入等桌面操作。
手动运行桌面代理模式：
dotnet WebApplication.dll --desktop-agent
⚠️ 桌面代理仅支持 Windows，Linux 无需此功能。
Q: 访问出现 500/502 错误？
- 检查
appsettings.json是否存在且格式正确 - 确认已安装 .NET 8 Hosting Bundle
- 查看 Windows 事件查看器中的错误日志
Q: Hangfire 面板无法访问？
- 确认已使用正确的账号密码登录
- 检查浏览器是否阻止了 Cookie
Q: 远程控制功能无法使用？
- 确认应用以管理员权限运行
- 在 IIS 部署时，检查应用池是否配置为
LocalSystem - 验证
RemoteControl:ElevatedAgent配置是否正确
本项目采用 Selective Freedom License (SFL) v1.0 授权，详见 LICENSE。