# openlist-nat

**Repository Path**: kukieol/openlist-nat

## Basic Information

- **Project Name**: openlist-nat
- **Description**: OpenList + Natter 内网穿透的 KernelSU/Magisk 模块：手机上的网盘，公网直达
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-17
- **Last Updated**: 2026-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# openlist-nat

把 **OpenList** 和 **Natter** 打洞塞进一个 Android 模块：手机上跑一个网盘，从公网直接访问，不租服务器、不做端口映射。

刷入即用，开机自启，KernelSU / Magisk 的「操作」按钮和 WebUI 都能开关。

~~~
              公网                       运营商 NAT / CGNAT                手机
  浏览器 ───────────▶ 114.x.x.x:5171 ──────────────▶ 192.168.2.7:5244 ──▶ OpenList
                            ▲
                            │ 60s 心跳续命；地址一变就重打并重新上报
                            │
                     Natter（STUN 打洞，socket 转发）
~~~

## 它能做什么

- 手机上的 OpenList（网盘 / WebDAV），局域网 http://手机IP:5244 直接访问
- 通过 STUN 打洞拿到公网 IP:PORT，外网也能访问，**前提是 NAT 是全锥形（EIM+EIF）**
- 打洞地址会变（重拨、映射回收），模块内置守护循环，变了自动重打
- 可选：配合 [natter-redirect](https://github.com/qiuyuxc/natter-redirect) 拿一个固定域名，访问域名自动 302 到当前地址

## 特性

| | |
|---|---|
| 零外部依赖 | OpenList、静态 musl Python 全部打包进模块，不装 Termux、不占用户空间 |
| 开机自启 | service.sh 等 sys.boot_completed 后拉起 OpenList + 守护循环 |
| WebUI | 状态、开关、日志、上报域名，一个页面搞定 |
| 地址漂移 | 守护进程每 10s 比对局域网 IP，变了就重启 Natter 并重新上报 |
| 数据隔离 | 数据在 /data/adb/openlist，配置在 /data/adb/openlist-nat，升级模块不丢 |
| 低功耗 | 实测 CPU 约 0.02%、内存约 103MB、每分钟 9 次唤醒，不持 wakelock |

## 安装

1. 到 Releases 下载 openlist-nat-*.zip
2. KernelSU / Magisk 管理器 → 模块 → 从本地安装 → 重启
3. 重启后打开 WebUI（管理器 → 模块 → 打开），或在浏览器访问 http://手机IP:5244

首次启动 OpenList 会在 service.log 里打印随机管理员密码；也可以自己设：

~~~bash
su -c '/data/adb/modules/openlist-nat/bin/openlist admin set 你的密码 --data /data/adb/openlist'
~~~

## 使用

**WebUI**：状态卡片 + 启动/停止/重启/日志/复制入口，改上报域名后自动重启 Natter 重新上报。

**操作按钮**：不打开 WebUI 时，模块页的「操作」按钮切换整套服务的启停，并在 toast 里显示局域网地址、当前映射和域名。

**命令行**：

~~~bash
su -c '/data/adb/modules/openlist-nat/ctl.sh status'
su -c '/data/adb/modules/openlist-nat/ctl.sh start'   # 也可以 stop / restart / log
su -c '/data/adb/modules/openlist-nat/ctl.sh set-domain https://nat.example.com'
~~~

set-domain 传空字符串即清空，只打洞不上报。

## 固定域名（可选）

DNS 只能存 IP，存不了端口，所以打洞地址没法直接写进 A 记录。做法是让域名只负责跳转：

1. 部署 [natter-redirect](https://github.com/qiuyuxc/natter-redirect)（Cloudflare Worker + KV，单文件）
2. 在 WebUI 里填上你的域名，或者 ctl.sh set-domain https://你的域名
3. 之后访问域名会 302 到当前 IP:PORT，path 和 query 都保留

不配也能用，只是每次都得自己看当前映射地址。

## 目录

| 路径 | 说明 |
|---|---|
| /data/adb/modules/openlist-nat | 模块本体，升级时整个替换 |
| /data/adb/openlist | OpenList 数据（数据库、文件），升级不动 |
| /data/adb/openlist-nat/config | SITE=... 上报域名，留空即不上报 |
| /data/adb/openlist-nat/secret | 上报密钥，与 Worker 的 SECRET 一致 |

## 自己构建

二进制不进仓库，build.sh 负责下载和组装（首次约 180MB，缓存在 .cache/）：

~~~bash
./build.sh
# 产物 dist/openlist-nat-<version>.zip
~~~

依赖 curl tar zip；有 llvm-strip 或 strip 时会顺手给 python 瘦身。

可覆盖的版本变量：OPENLIST_VER、PY_VER、PBS_TAG、ALPINE。

构建时会为每个包生成独立的上报密钥（natter/secret），不随仓库分发。

## 已知限制

- 只支持 **arm64**，且需要**全锥形 NAT**；对称 NAT / 双重 CGNAT 打不通
- 端口固定 5244，映射端口由运营商分配，会变
- 跳转是 http://，Natter 穿的是裸 TCP，没有 TLS；要 HTTPS 得自己在前面加反代
- 运营商可能随时收紧 NAT 策略，打洞不是长期方案

## 许可

GPL-3.0。natter/natter.py 来自 [MikeWang000000/Natter](https://github.com/MikeWang000000/Natter)（GPL-3.0），已针对高并发连接和吞吐打了补丁，版权归原作者。

OpenList 为 Apache-2.0，Python 为 PSF License，均以二进制形式随包分发。