# yueya

**Repository Path**: willdomybest/yueya

## Basic Information

- **Project Name**: yueya
- **Description**: 一个 Python 文件把电脑变成浏览器里的文件管理器：局域网私有云、上传下载、在线预览、FTP 直传、网页终端与进程管理。A single Python file that turns any computer into a browser-based file manager — LAN private cloud, upload/download, preview, FTP, web ter
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RemoteFM · 因热爱而行动

**中文** | [English](README_EN.md)

**一个 Python 文件，安全的把任何一台电脑变成你浏览器里的文件管理器。**

## 它适合谁

- 把家里的电脑当成**私有云盘**，在局域网或 VPN 里随时存取；
- 给**无头服务器、树莓派、NAS** 配一个图形界面，不用再折腾 Samba；
- 在**手机上**管理电脑文件，躺床上也能传照片、看视频；
- **临时给同事传文件**：发个链接或开个 FTP，对方零安装。

## 快速开始

### 方式一：下载免安装版（Windows，不需要 Python）

到 [发行版页面](https://gitee.com/willdomybest/yueya/releases/latest) 下载 `RemoteFM-v1.4.2-windows-x64.zip`，
解压后双击 `RemoteFM.exe` 就能用——**不用装 Python、不用装依赖、没有安装过程**，解压即跑。

> 能访问 GitHub 的话也可以从 [GitHub Releases](https://github.com/willdomybest/yueya/releases/latest) 下载；
> macOS / Linux 请用下面的方式二，或自行用 `build_exe.py` 打包。

### 方式二：源码运行（Windows / macOS / Linux）

```bash
pip install flask requests pyftpdlib cryptography
python RemoteFM.py
```

两种方式启动后都一样：浏览器打开 <https://127.0.0.1:8880>，默认账号 `admin / admin123`。
用 `http://` 打开也会自动 307 跳到同端口 HTTPS；首次运行使用自签证书，浏览器提示「不安全」时点
「高级 → 继续访问」即可（HTTPS 默认开启，可随时在配置里关掉）。

- `cryptography` 用于首次启动**自动生成自签 HTTPS 证书**（默认开启 HTTPS）；不想装可以二选一：
  在配置里把 `https.enabled` 改成 `false`，或自己提供证书路径（`https.cert` / `https.key`）。
  注意：默认配置下**拿不到证书会拒绝启动**，而不是悄悄降级成明文 HTTP。
- 不需要 FTP 功能就不装 `pyftpdlib`，程序会自动跳过。
- 已经装了 [uv](https://docs.astral.sh/uv/) 可以一行运行：`uv run RemoteFM.py`。
- 手机或局域网其他设备访问：`https://本机IP:8880`（`http://` 会自动跳转），首次运行请让防火墙放行。

## 你是不是也遇到过

想把电脑里的照片传到手机上，聊天软件先把画质压了一遍；想取回家里那台老笔记本上的资料，得先装个网盘客户端，登录、同步、慢慢等；临时要发个 2GB 的素材给同事，对方还得先装一个“传输工具”。

明明只是拿自己的文件，却总要先把文件交给别人的服务器。

**RemoteFM 不绕这一圈：不开账号、不上传云端，直接在你自己的机器上开一扇门。**

![界面](screenshots/file-manager.png)

打开浏览器，就是这台电脑的文件列表。上传、下载、预览、压缩解压一样不少，还带 FTP、网页终端和进程管理。机器没有显示器、没有图形界面也没关系——你需要的只是一个浏览器。

## 为什么可以放心用

- **只有一个文件**：后端、页面、前端全在 `RemoteFM.py` 里，除首次启动自动生成的 `RemoteFM.cfg` 外没有数据库、没有构建步骤。想读能读，想改能改。
- **数据不出门**：不联网上报、没有埋点、不收集任何信息，文件只在你自己和你信任的设备之间流动。
- **30 秒起步**：装好 Python 后两条命令即可，浏览器打开 `http://127.0.0.1:8880`（自动跳转 HTTPS）就能用。
- **旧机器也跑得动**：Windows / macOS / Linux 通吃，Python 3.8 起步，树莓派、NAS、十年前的老笔记本都不挑。

## 它能做什么

| | 能力 |
| --- | --- |
| 📁 **文件管理** | 浏览、搜索、排序、多选，复制 / 移动 / 删除 / 新建文件夹，ZIP 压缩与解压，根目录随时切换 |
| ⬆️ **上传下载** | 32MB 分片上传、断点续传；图片 / 视频 / 文本在线预览；填个 URL 让服务器替你下载 |
| 🌐 **FTP 直传** | 与网页共用账号和根目录，复制链接粘进资源管理器就能拖拽，几十 GB 的大文件更稳 |
| 💻 **网页终端** | 命令实时回显，命令历史、Tab 补全、后台任务，工作目录跟着你浏览的文件夹走 |
| ⚙️ **进程管理** | CPU / 内存占用与完整命令行一目了然，一键结束卡死的进程 |

## 用之前，请先读这一句

它的登录密码等于这台电脑的控制权——**请改掉默认密码，只在局域网或 VPN 内使用，不要直接暴露到公网**，详细建议见下方「安全」一节。

**MIT 协议**，可自由使用、修改、分发，包括商业用途。

## 运行环境

| 项目 | 要求 |
| --- | --- |
| Python | **3.8 及以上**（实测 3.12.10） |
| 操作系统 | Windows / macOS / Linux，无图形界面的服务器同样可用 |
| 依赖 | `Flask`、`requests`、`cryptography` 必需（`cryptography` 用于生成自签 HTTPS 证书）；`pyftpdlib` 可选，不装则不启用 FTP |
| 浏览器 | Chrome / Edge / Firefox / Safari 等现代浏览器，手机浏览器也可用 |
| 其他 | 不需要数据库、不需要 Node.js、不需要 Docker |

实测组合：Windows 11 + Python 3.12.10 + Flask 3.1.3 + Werkzeug 3.1.8 + requests 2.34.2 + pyftpdlib 2.2.0 + cryptography 46.x。

## 配置示例

### 配置文件

所有配置收敛在**一个** `RemoteFM.cfg` 里（打包版在 exe 同目录，可用 `SD_CONFIG` 指定路径），首次启动自动生成，
**每一项都带 comment 说明用法，且 comment 放在该项最后**：

```json
{
  "comment": "RemoteFM 唯一配置文件。改完重启生效；同名环境变量优先级更高。",
  "version": 1,
  "encryption": {
    "comment": "敏感项加密方式：base64（默认，种子可空）/ xor（需种子）/ hmac-sha256（需种子，带完整性校验）",
    "type": "base64",
    "seed": ""
  },
  "settings": {
    "https":    { "enabled": {"value": true, "comment": "…"}, "cert": {…}, "key": {…} },
    "auth":     { "admin_user": {…}, "admin_pass": {"value": {"__enc": {…}}, "comment": "…"} },
    "ftp":      { "enabled": {…}, "user": {…}, "pass": {…}, "port": {…}, "passive_start": {…} },
    "server":   { "host": {…}, "port": {…}, "secret": {…}, "root": {…} },
    "files":    { "users": {…}, "token": {…}, "key": {…} },
    "terminal": { "history_hours": {"value": 48, "comment": "远程命令接口请求记录保留时长"} }
  }
}
```

- **HTTPS（单端口双协议，默认开启）**：`https.enabled` 默认为 `true`（设为 `false` 关闭），仅 `server.port`
  一个端口就同时提供 HTTPS 与明文跳转——按 TLS 握手首字节自动识别协议，`https://主机:8880` 直接访问，
  `http://主机:8880` 则原地 307 跳到**同端口** HTTPS（隧道只需映射 `server.port` 一个端口）。证书路径留空时
  首次启动自动生成自签证书（`remotefm_cert.pem` / `remotefm_key.pem`），浏览器会提示不受信任。拿不到可用证书时
  **拒绝启动**，绝不会悄悄降级成明文 HTTP。
- **敏感项自动加密**：管理员密码、FTP 密码、会话密钥按 `encryption` 指定的方式加密保存，磁盘上只有密文与校验值；
  服务重启后自动解密，登录与 Token 回显都继续有效。想手工写密文，执行 `python RemoteFM.py --encrypt "新密码"` 把结果粘进去即可。
- **环境变量优先于配置文件**：`SD_CONFIG`、`SD_HOST`、`SD_PORT`、`SD_ROOT`、`SD_USER`、`SD_PASS`、`SD_SECRET`、
  `SD_FTP`、`SD_USERS`、`SD_TOKEN_FILE`、`SD_KEY_FILE`、`SD_HTTPS`、`SD_HTTPS_CERT`、`SD_HTTPS_KEY`，
  适合临时覆盖而不改文件。
- `RemoteFM.cfg` 已加入 `.gitignore`，**不要提交**（里面有账号密码）。

下面这些环境变量同样可用（优先级高于配置文件）：

### 多用户与权限

| 角色 | 能做什么 |
| --- | --- |
| **超级用户** | 默认 `admin / admin123`（可用 `SD_USER` / `SD_PASS` 修改）。切换根目录、使用终端与进程管理、进入用户管理（添加 / 编辑 / 删除普通用户、修改任意密码） |
| **普通用户** | 由超级用户添加，**目录范围可多选**（例如 `D:\tt` + `D:\App` + `E:\Lenovo`）。只能在这些目录内浏览、上传、下载、压缩、重命名、复制、移动、删除；跨目录范围的移动会被拒绝。看不到终端、进程、FTP，也**看不到用户管理入口**；即使输入 `../` 也无法越出范围 |

用户管理是接近「进程管理」的全屏面板：左侧账号表格（用户名 / 角色 / 目录范围 / 操作），右侧就地展开添加、编辑（改名、改密、调整目录范围）表单，不会用弹窗盖住界面。

用户数据保存在程序同目录的 `users.json`（打包版为 exe 同目录），密码使用「随机盐 + SHA-256」存储；
目录不可写时会自动改用用户主目录下的 `.remotefm/users.json`，也可用 `SD_USERS` 指定路径。
添加普通用户时根目录留空，会在超级用户根目录下自动创建同名文件夹。

**根目录也可以留空**：留空表示「整台计算机」，界面会直接列出所有盘符（Windows 为 C:/、D:/…），
可以浏览任意位置；超级用户的 `SD_ROOT` 设为空字符串同样是这个效果。用户管理是独立的全屏面板（和进程管理一致），
左侧列出全部账号与根目录，右侧就地添加用户或修改密码，不会用弹窗盖住界面。

Windows（PowerShell）：

```powershell
$env:SD_ROOT="D:\share"; $env:SD_USER="me"; $env:SD_PASS="换成强密码"; $env:SD_PORT="8899"; python RemoteFM.py
```

Linux / macOS：

```bash
SD_ROOT=/home/me/share SD_USER=me SD_PASS='换成强密码' SD_PORT=8899 SD_FTP=0 python RemoteFM.py
```

只允许本机访问（配合反向代理）：`SD_HOST=127.0.0.1 python RemoteFM.py`

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `SD_USER` / `SD_PASS` | `admin` / `admin123` | 登录账号，网页与 FTP 共用 |
| `SD_ROOT` | Windows 为 `D:\`，其他系统为用户主目录 | 被管理的根目录 |
| `SD_HOST` / `SD_PORT` | `0.0.0.0` / `8880` | 监听地址与网页端口 |
| `SD_FTP` / `SD_FTP_PORT` | `1`（启用）/ `2121` | FTP 开关与端口，被动端口 60000-60049 |
| `SD_FTP_PASSIVE_START` | `60000` | 被动端口起始值（连续 50 个） |
| `SD_SECRET` | 每次启动随机 | 会话密钥，固定它可让登录状态在重启后保持；同时作为落盘加密密钥 |
| `SD_TOKEN_FILE` | 与 `users.json` 同目录的 `token.json` | 远程命令接口的 Token 存储位置 |
| `SD_KEY_FILE` | 与 `users.json` 同目录的 `key.bin` | 落盘加密密钥文件；设置了 `SD_SECRET` 时改由它派生 |

## 打包成可执行文件

不想自己打包的话，直接下载 [发行版](https://gitee.com/willdomybest/yueya/releases/latest) 里的现成 exe 即可。

```bash
python build_exe.py
```

产物在 `dist/`：可执行文件 + `LICENSE` + `THIRD_PARTY_NOTICES.txt` + `licenses/`（各依赖的许可证全文）。
首次运行会自动安装 PyInstaller；图标由脚本内联生成，不需要额外的资源文件。

**运行程序本身只需要 `RemoteFM.py` 一个文件**，`build_exe.py` 只在打包时使用。
发布二进制时请把这几项一起打包：BSD / Apache-2.0 / MPL-2.0 都要求随二进制保留版权与许可声明。

## 安全

**登录密码等于这台电脑的控制权**：它能读写文件、删除文件、执行命令。

- 用之前改掉默认密码，用普通用户运行，并把 `SD_ROOT` 指向需要管理的目录；
- 只在局域网或 VPN 内使用，不要直接暴露到公网；
- HTTPS 已默认开启（首次运行自动生成自签证书，浏览器会提示不受信任）；对公网提供服务时请换上可信证书，
  并置于带访问控制的反向代理之后。

程序不联网上报、没有埋点，唯一的本地写入是系统临时目录中的上传分片；
请只在自己拥有或已获授权的机器上使用，软件按 MIT 协议“原样”提供，不附带任何担保。

## 功能

### 文件管理

浏览、搜索、排序、多选，复制 / 移动 / 删除 / 新建文件夹，ZIP 压缩与解压，根目录随时切换。

![文件管理](screenshots/file-manager.png)

### 上传与传输

32MB 分片上传与断点续传，图片 / 视频 / 文本在线预览，也可以填一个 URL 让服务器替你下载。

![上传方式](screenshots/upload.png)

### FTP 直传

与网页共用账号和根目录，复制链接即可粘贴到资源管理器或 FileZilla（资源管理器原生支持 FTP、不支持 SFTP），
适合几十 GB 的大文件。

![FTP](screenshots/ftp.png)

### 网页终端

执行命令并实时回显，支持命令历史、Tab 补全、后台任务，工作目录跟随当前浏览的文件夹。

![终端](screenshots/terminal.png)

### 远程命令接口（Token）

终端面板右上角的 🔑 打开「远程命令接口」：右上角是一个**状态开关**，打开即生成 Token；
Token 行右端右对齐地放着开关，旁边是三个小图标 —— 👁 显示 / 📋 复制 / 🔄 刷新（默认隐藏明文）。

```bash
# GET（最省事；命令里的空格要写成 %20 或 +）
curl "http://<你的IP>:8880/api/terminal/exec_token?token=<TOKEN>&cmd=dir"

# POST JSON（推荐，命令不落在 URL 里）
curl -X POST "http://<你的IP>:8880/api/terminal/exec_token" \
  -H "X-Token: <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"dir","cwd":".","timeout":30}'
```

返回 `{"success":true,"exit_code":0,"duration":0.05,"cwd":"...","output":"..."}`；Token 错误或接口停用时返回 401。
面板右侧保留**最近 48 小时**的请求记录（时间 / 来源 / 命令 / 退出码 / 耗时），每 5 秒自动刷新。

**落盘的敏感信息是加密的**：Token 采用对称加密（HMAC-SHA256 密钥流 + encrypt-then-MAC），磁盘上只有
`nonce + 密文 + MAC`，重启后自动解密回显，Token 和功能都继续有效。密钥优先取 `SD_SECRET`（推荐，这样密钥不落盘），
否则在程序目录生成权限 600 的 `key.bin`。用户密码则是单向哈希，不回显。

### 进程管理

查看进程、CPU 与内存占用、完整命令行，可按名称 / PID / 命令搜索，一键结束进程。

![进程](screenshots/processes.png)

## 许可证

[MIT License](LICENSE) © 2026 willdomybest：可自由使用、修改、分发，包括商业用途，保留版权与许可声明即可。本文档与 `screenshots/` 中的截图同样以 MIT 发布。

### 第三方组件

依赖通过 pip 安装，仓库中不包含任何第三方代码；各组件版权归原作者所有，许可证均与 MIT 兼容：

| 组件 | 许可证 |
| --- | --- |
| Flask、Werkzeug、Jinja2、itsdangerous、click、MarkupSafe、idna | BSD-3-Clause |
| blinker、urllib3、charset-normalizer、pyftpdlib | MIT |
| requests | Apache-2.0 |
| certifi | MPL-2.0 |

如果将来把依赖一起打包分发（例如 PyInstaller 单文件版），需要随包附上这些组件的许可文本。

### 贡献

欢迎 Issue 和 PR，提交 PR 即表示你同意自己的贡献以 MIT 协议发布。

## 免责声明

这个项目是出于兴趣写出来的。作者希望它真的帮到你，也尽力让它保持可靠，但有些话还是要说在前面：

- **软件按「原样」提供**，不附带任何明示或暗示的担保，包括适销性、特定用途适用性与不侵权；
- 使用本项目的**全部或部分代码、以及由它编译出的程序**所产生的一切后果，由使用者自行判断和承担，作者不承担任何法律责任；
- 它具备文件读写、删除与命令执行能力，**请务必改掉默认密码、只在局域网或 VPN 内使用**，并确认你有权处置那台机器上的数据；
- 重要数据请提前备份。作者乐于认真处理你反馈的问题，但无法对数据丢失、服务中断或安全事件作出赔偿承诺。

如果这些内容与你的使用场景不太相符，建议先别投入生产环境；有任何疑问都欢迎在 Issue 里聊，我会尽量给出建议。