TermuxPanel 用户使用手册

适用：当前原生 Termux 部署，Go 面板 + Nginx + PHP-FPM + MariaDB。日常使用不需要手机 Root。界面与本文均为简体中文。

本文中的端口和域名是示例，以面板“端口管理”的实际配置为准。示例使用新网站 my_site、域名 mysite.test、手机网站端口 8081，避免与现有示例网站可能使用的 8080 冲突。本文不包含任何实际密码。

1. 先认识面板、网站、数据库

管理后台端口与网站端口不同。打开 9090 看见管理后台，不代表 8081 的网站已建好。Unix Socket 是手机上的本地通信文件，不占 3306、9000 等 TCP 端口。

新安装默认仅本机；本次设备已按用户要求启用管理面板的局域网访问。网站可在“网站”或“端口管理”选择访问范围。电脑浏览器的 127.0.0.1 指电脑自己，手机浏览器的 127.0.0.1 指手机自己；仅本机模式需通过转发连接。0.0.0.0 是监听配置，访问时用手机真实 IP。

2. 域名、IP、端口与解析的关系

访问地址示例：http://mysite.test:8081/index.php。

“在网站中填写域名”只是写入 Nginx 的网站配置，不会自动给你购买域名或添加 DNS 记录。当前界面一个网站填写一个域名，不填写 http://、端口、目录、空格或通配符。

普通 A / AAAA 记录保存 IP，不能填写 IP:8081。CNAME 保存另一个域名，也不是“域名加端口”。需要非标准 HTTP 端口时，把端口写在浏览器地址中，或由入口反向代理转换。常规 HTTP 默认 80、HTTPS 默认 443，但本项目网站默认使用高位端口。

本地 hosts 只影响修改过的那台电脑；公共 DNS 可影响使用该解析结果的访客。测试可以使用 mysite.test；example.com 等文档域名不属于你，不能给它添加公共记录。不要向公共 DNS 填 127.0.0.1 来让所有人访问手机，那会让访客访问各自的本机。

参考：DNS 记录类型、IANA 示例域名。

3. 通过 USB 从电脑访问

手机开启 USB 调试，连接电脑并接受调试授权。ADB 工具应是你已审查的 Android 平台工具或当前项目内提供的 adb-fastboot 目录，不执行刷机或 fastboot 命令。

在电脑 PowerShell，进入当前项目目录：

.\adb-fastboot\adb.exe devices -l
.\adb-fastboot\adb.exe forward tcp:9090 tcp:9090
.\adb-fastboot\adb.exe forward tcp:8081 tcp:8081
.\adb-fastboot\adb.exe forward --list

然后电脑打开 http://127.0.0.1:9090，使用 admin 和自己的面板密码登录。网站建好后访问 http://127.0.0.1:8081。域名访问见第 6 节。

ADB 转发左边是电脑端口，右边是手机端口。若电脑 8081 已被其它程序占用，可以改用不同的电脑端口：

.\adb-fastboot\adb.exe forward tcp:18081 tcp:8081

此时电脑网站地址是 http://mysite.test:18081，手机 Nginx 仍监听 8081。面板端口暂时保持电脑 9090 对应手机 9090，当前 Host 检查会拒绝其它浏览器端口；不要把这个网站的端口映射技巧直接套到面板。

拔掉 USB、ADB 重启或设备重启后，转发可能需要重新建立。删除自己的单条映射用：

.\adb-fastboot\adb.exe forward --remove tcp:8081

不要使用 remove-all 清除其它项目的转发。电脑 ADB 映射不会自动出现在手机端口表中，需在电脑执行 forward --list。

参考：Android ADB 官方说明。

4. 局域网直接访问与可选 SSH 隧道

局域网直接访问

手机和电脑连接同一个可互访的家庭网络。手机 Wi-Fi IP 在 Android 设置的 Wi-Fi 详情中查看；例如手机是 192.168.31.86，面板监听 0.0.0.0:9090，则电脑打开 http://192.168.31.86:9090。IP 改变后使用新的地址；建议在路由器给手机保留 DHCP 地址。

“端口管理”顶部显示管理面板监听配置。面板 LAN 模式仍要求登录，限制本机/私网 TCP 来源，校验 Host 为实际接收连接的本机 IP，保留 Origin/CSRF 校验。当前没有内建 HTTPS，HTTP 不加密；需要加密可继续使用下面的 SSH 隧道。不要把面板 9090 转发到公网，不能依靠私网来源限制防御路由器改写来源的映射。

网站在“网站”勾选“允许局域网 / 路由器转发”，或在“端口管理”选择网络访问并启用监听后，可访问 http://手机实际IP:网站端口，例如 http://192.168.31.86:8080。仅本机模式不会接受 LAN 连接；手机 IP 不属于同一个网络、访客 Wi-Fi 隔离、代理等也会影响互访。

局域网域名可把电脑 hosts 中的 mysite.test 解析到手机 IP（而不是 127.0.0.1），然后访问 http://mysite.test:8081；这是网站域名，管理面板仍使用实际 IP:9090。

本机切换管理面板访问范围后需重启面板；以下不修改网站、数据库或路由器。当前设备已经启用 LAN，无需重复执行：

"$HOME/.local/bin/panel" set-listen 0.0.0.0:9090
sv restart "$PREFIX/var/service/termux-panel"

收回面板局域网入口：

"$HOME/.local/bin/panel" set-listen 127.0.0.1:9090
sv restart "$PREFIX/var/service/termux-panel"

可选的加密 SSH 隧道

前提：已建立你自己的 SSH 公钥登录，并明确允许一个受控的手机局域网 SSH 入口。当前开发时使用的回环 SSH 入口及临时开发公钥，不等于已经为你配置了长期 Wi-Fi 管理。

手机 Termux 的用户名用 whoami 查看。手机 Wi-Fi IP 在 Android 的 Wi-Fi 详情中查看；部分系统不允许 Termux 用 ip/ss 读取完整网络信息。

在电脑生成专用密钥，已有密钥不要覆盖：

ssh-keygen -t ed25519 -f "$env:USERPROFILE\.ssh\termux-panel"

只将 .pub 公钥通过已授权方式追加到手机 ~/.ssh/authorized_keys，并设置 ~/.ssh 为 700、authorized_keys 为 600。不要复制私钥到手机或聊天中。不要以设置一个明文 SSH 密码代替公钥配置。

如果你选择开一个新的局域网 SSH 入口，先确认对应手机 IP 和端口未被使用。以下手机命令属于可选手工网络配置，需要你理解并同意后执行；示例 192.168.1.50 必须替换为手机真实局域网 IP：

sshd -e -p 8023 -o ListenAddress=192.168.1.50 -o PasswordAuthentication=no -o KbdInteractiveAuthentication=no -o PidFile="$HOME/.ssh/tpanel-lan-sshd.pid"

此命令只增加一个绑定指定 LAN IP 的 SSH 实例，不修改面板或网站监听。不要在路由器上将这个管理入口转发到公网。手机 IP 改变时需重新审查监听；不同 ROM 的网络限制需要实测。

电脑保持以下隧道命令运行，将 USER_NAME、PHONE_LAN_IP 换成真实值：

ssh -i "$env:USERPROFILE\.ssh\termux-panel" -p 8023 -N -o ExitOnForwardFailure=yes -L 9090:127.0.0.1:9090 -L 8081:127.0.0.1:8081 USER_NAME@PHONE_LAN_IP

访问地址仍是电脑的 http://127.0.0.1:9090 和网站的本地域名地址。关闭隧道窗口会中断电脑访问，但不会停止手机上的网站和数据库。示例 LAN 配置不是当前自动启用功能，尚未按所有 ROM 验证。

5. 新建第一个网站

先进入“服务管理”，确认项目 Nginx 和 PHP-FPM 处于运行状态。PHP 网站创建时会验证 PHP 真正执行，FPM 停止或地址尚未探测会导致创建失败并回滚。

打开“端口管理”，检查计划使用的 8081；已有项目使用时选其它高位端口。列表没有出现某个端口，不证明它空闲；最终以建站时的绑定和 Nginx 检查为准。

进入“网站”，填写：

点击“检测配置并发布”。面板会生成候选配置、执行 nginx -t、原子切换、重载、用配置代次和临时访问探针验证，然后登记。失败会返回错误并尝试恢复旧版；不要反复点击或直接编辑生成文件来绕过检测。

默认根目录是手机 $HOME/sites/my_site/public，位于 Termux 私有目录。网站创建成功不会自动安装 CMS，也不会自动生成永久首页。

进入“文件”，选择刚创建的网站，新建 index.php 并保存以下内容：

<?php
header('Content-Type: text/plain; charset=utf-8');
echo '我的网站已经运行';

纯静态站点可创建 index.html：

<!doctype html>
<html lang="zh-CN"><meta charset="utf-8"><title>我的网站</title><h1>网站运行正常</h1></html>

电脑建立第 3 / 4 节的 8081 转发，设置第 6 节的 hosts，然后打开 http://mysite.test:8081。测试完成不需要保留 phpinfo 或包含数据库密码的公开页面。

6. 为本地网站解析域名

在 Windows 以管理员权限打开文本编辑器，打开 C:\Windows\System32\drivers\etc\hosts，追加一行：

127.0.0.1 mysite.test

保留其它内容，文件名必须是 hosts，不是 hosts.txt。这一行让这台电脑把 mysite.test 连接到电脑的回环入口；手机网站靠 ADB / SSH 隧道到达。

浏览器访问 http://mysite.test:8081。如果左侧电脑映射用的是 18081，访问 http://mysite.test:18081。hosts 中不写端口。

无需先修改 hosts 的检查方法（电脑 PowerShell 使用 curl.exe，避免与某些 PowerShell 别名混淆）：

curl.exe --noproxy "*" -H "Host: mysite.test" http://127.0.0.1:8081/

或指定本次请求的解析：

curl.exe --noproxy "*" --resolve mysite.test:8081:127.0.0.1 http://mysite.test:8081/

如果这些请求成功而浏览器失败，检查 hosts、系统/浏览器代理、浏览器 DNS 缓存与 HTTPS 自动升级。nslookup 通常直接查 DNS，不适合作为 Windows hosts 是否生效的唯一验证；用浏览器或上面的实际 HTTP 请求判断。

7. 建多个网站、改端口、停用和删除

第二个网站使用另一个端口，再增加对应 ADB / SSH 转发和 hosts 记录。当前版本没有在一个 80/443 监听上批量管理多个域名的向导。

编辑已有网站时点其“编辑”，确认标识未变，修改域名、名称或端口，再检测发布。改变手机网站端口后，同步更新电脑的转发和访问 URL。停用会移除受管监听，但保留内容；启用会重新检测。

删除网站需要输入“删除 网站标识”的完整确认文字。删除的是站点登记和受管配置，文件默认保留。删除文件是另一项操作，不要将删除配置当作已经清理所有数据。上一版配置可以通过“恢复上一版站点配置”回滚；该历史是整个受管配置集，不是每个网站各一条历史。

Nginx 的 server_name 与 HTTP Host 共同参与站点选择；独立端口上只有一个 server 时，直接 IP 访问也可能命中该默认站点。域名不是访问密码。参考：Nginx 请求处理规则。

8. 文件管理、批量上传与批量下载

“文件”只操作选中网站的 public 根目录。列表提供文件/目录图标、复选框、大小、修改时间和单项操作；顶部可切换站点、输入相对目录、使用面包屑/上级目录导航、搜索当前目录文件名。

批量上传

1. 选择网站，进入上传目标目录；点击“上传文件”。
2. 在窗口中点击选取多个文件，或把多个文件拖到上传区；“继续添加”可以补充文件。
3. 查看队列中的文件名、大小和预检提示，不支持的类型、超限文件会明确标记。
4. 默认保留目标目录同名文件；确认需要替换时勾选“覆盖目标目录中的同名文件”。
5. 点击“开始上传”，查看批次传输进度与每个文件最终结果。部分失败不会撤销已经成功的文件；重试只发送未成功项目。

每批最多50个文件，默认单文件2 MiB、整批32 MiB；可在“面板设置”调整，单文件允许1–256 MiB，整批不小于单文件且最多512 MiB。上传窗口显示当前限制。支持 php、html、css、js、json、txt、md、svg，以及 png、jpg/jpeg、gif、webp、ico。图片保持原始字节，上传不会转成文本；同一批同名文件会报告重复。默认不覆盖通过独占创建保护，允许覆盖时先写完临时文件再替换。上传窗口保持显示目标站点和目录，传输中不能切换目标或关闭窗口。

传输进度表示浏览器上传请求的进度，不是每个文件已经落盘；以最终逐项“上传成功”为准。断网/超时会显示结果未确认，请刷新目录核对，再决定是否覆盖重试。

多选与打包下载

1. 勾选文件或目录；表头复选框选择当前名称筛选结果，每次最多50项。“取消选择”清空选择。
2. 点击“打包下载所选”。服务端准备完整ZIP后交给浏览器下载，名称为“网站标识-files.zip”。
3. 目录会包含其内部普通文件、子目录和空目录；ZIP保留相对目录和中文名称，不加入手机绝对路径。

最多选择50项，展开后最多1000条目、32层目录，文件内容总计最多64 MiB；遇到符号链接、特殊文件、保留名称或超限会拒绝整个打包，避免得到漏文件的“成功”归档。打包期间变化的文件可能使请求失败，需要重新下载；这不是一致性快照备份。ZIP临时文件放在面板私有数据目录，正常请求结束后删除，不放进网站public。

单个文件可点列表“下载”，支持大文件流式下载并保留原文件名和字节；目录或多个选择使用“打包下载”。文本编辑仍限2 MiB，ZIP内容总量仍限64 MiB，这两项不随上传设置变化。一次目录列表最多显示1000项，更多文件请分子目录管理；搜索仅筛选当前已列出的内容。

编辑、新建和程序部署

点击“新建文件”，填写相对路径与UTF-8内容后保存；文本文件可点“打开”编辑。二进制文件只读展示提示，修改请重新上传并选择覆盖。新建目录只需填写当前目录下的名称。删除当前文件仍需目标文字确认；批量删除、批量重命名和移动暂未提供。

路径使用相对路径，例如 assets/logo.png，不填写系统绝对路径。越界路径和符号链接会被拒绝，不能借文件页面查看任意系统目录。

大型CMS压缩包、ZIP上传/解压和Git拉取暂未提供Web向导。可信的大文件可通过已配置的SSH/SFTP上传到对应私有目录，先核对来源和解压路径。不要把含秘密的配置放进public。框架自定义Nginx规则、通用伪静态和多PHP版本尚未提供UI，不能仅上传文件就宣称所有CMS可用。

9. 创建数据库与连接 PHP

在“服务管理”确认 MariaDB 正在运行。管理员连接凭据由本机受限文件保存，不在网页中填写数据库 root 密码。

“数据库”展开创建表单，填写数据库（例如 tp_mysite）、普通账号（例如 tp_mysite_user）和密码。数据库与账号分别命名，均以 tp_ 开头；密码14–256字节。创建成功后只授予该数据库权限。不要把面板 admin 密码当成数据库密码。

内置数据库管理器

点击数据库旁的“管理”，选择当前数据库与执行账号。旧版本创建的账号首次使用需展开“连接已有普通账号 / 保存连接密码”，输入该账号原密码验证，或者在“用户管理”重置密码。连接密码保存在手机私有目录的0600文件，不在页面回显；修改后也要更新网站程序中的旧密码。

数据表页列出表和视图，支持浏览前100行及查看结构。“SQL脚本”可直接输入或载入最多1 MiB的SQL；核对数据库并勾选确认后执行，最长30秒，结果最多显示64 KiB。查询更多数据时使用筛选和分页SQL。可执行建表、查询、更新及删除等授权语句，修改操作可能不可撤销，先备份现状。

“导入 / 导出”上传单个.sql，大小使用“面板设置”的单文件上传上限；勾选确认后以当前普通账号执行，最长3分钟。导出下载.sql并同时登记到“备份与恢复”，包含结构、数据、触发器、存储程序及事件。迁移脚本应兼容当前MariaDB版本及账号权限：涉及全局管理、其它数据库、DEFINER或跨版本语法的脚本可能失败。导入和多语句执行不保证整体事务，报错可能已部分修改，不能盲目重试。

“用户管理”可为当前库创建额外普通用户、修改已登记用户密码；改密需输入完整确认目标。网页SQL和导入使用普通账号、本地Socket和MariaDB客户端沙箱，不以root执行；不提供系统命令或全局数据库管理。

当前设备的数据库默认用 Unix Socket，不使用 127.0.0.1:3306。实际 socket 在“端口管理”的 MariaDB 行查看。PHP PDO DSN 示例：

mysql:unix_socket=/从端口管理复制的实际socket路径;dbname=tp_mysite;charset=utf8mb4

将普通账号凭据放在 public 之外、0600 的受限文件中，通过程序配置机制读取。文件管理页面只允许 public 内操作；public 外配置需通过本机或已授权 SSH 设置。不要把管理员 database.cnf 复制给网站。

数据库备份在“备份与恢复”创建，恢复前先备份现状并输入完整目标文字确认。恢复只允许登记的备份回到原库，校验损坏会被拒绝；数据库恢复不是整体事务，出错可能部分修改。

10. 使用端口管理

菜单“端口管理”上方提供网站 TCP 端口设置，下方提供配置和连接状态列表。

1. 先在“网站”创建站点，再进入“端口管理”选择该网站。
2. 填写 1024–65535 的独立 TCP 端口，不能占用面板端口或其它启用网站端口。
3. 选择“允许局域网 / 路由器转发（0.0.0.0）”并勾选“启用网站监听”，点击“检测并应用端口设置”。
4. 用手机实际 IP:端口访问。改回“仅手机本机”收回网络访问；取消“启用网站监听”关闭该网站端口，保留网站文件。

修改同一个端口的访问范围时会短暂重启项目 Nginx，影响其下所有网站；其它修改通常重载。变更先配置检查，再实际访问验证，失败尝试回滚，未完成事务会阻止继续变更。

这项功能修改项目 Nginx 的网站监听，不是 Root 防火墙工具，不会为没有服务的任意端口创建虚假“开放”状态，也不会自动修改路由器。网络模式监听所有 IPv4 接口，能否从公网到达仍由路由和运营商网络决定。

Android 可能禁止完整 netlink / 进程读取。页面会保留项目配置和实际端点结果，并显示“系统枚举受限”；没有出现在列表中不代表未使用或端口空闲。当前系统补充枚举仅 TCP LISTEN，不含 UDP、所有进程或所有网络命名空间。

数据库实时参数确认 skip_networking=1 时，不把其保留的 port=3306 参数显示成监听的 TCP 端口。SSH 与电脑上的 ADB 转发也不应被自动误认成面板业务监听。

11. 让公网域名访问网站

当前支持网站网络监听；没有自动路由器配置、自动 HTTPS 或内置穿透服务。DNS 解析成功只证明找到了 IP，不证明请求能进入手机。

通过自家路由器转发

先验证另一台局域网设备能够访问手机网站，再检查路由器 WAN 是否有可入站的公网 IPv4。运营商 CGNAT 不能只靠自家路由器转发解决；光猫/路由器双层 NAT 需要处理上层映射。不要把面板 9090 映射到公网。

网站已选择网络访问、手机 IP 已固定时，路由器添加 TCP 转发规则，例如：

路由器字段可参考 厂商端口转发说明。

关闭另一台测试设备的 Wi-Fi，使用移动网络访问 http://路由器实际公网IP:18080。不要仅在同一个 Wi-Fi 内测试公网地址，部分路由器不支持 NAT 回环。外部端口可与内部不同；若映射外部 80 到内部 8080，访问地址可以省略 HTTP 端口。运营商可能另有限制，以实际测试为准。

域名 A 记录指向路由器的真实公网 IPv4；非标准外部端口仍需写在 URL。动态公网地址改变时要更新解析；正式 HTTPS 需要另外部署证书和入口，不能把 HTTP 端口直接当成 HTTPS。

通过独立公网入口和隧道

另一种可以独立部署的入口结构：

访客域名 → 公网入口（HTTPS / 反向代理）
                         ↓ 已认证隧道
                 手机 127.0.0.1:8081

你需要拥有真实域名，并拥有公网可访问的入口。将实际网站子域名的 A 记录指向该入口 IPv4；有完整 IPv6 入站能力时才增加 AAAA；需要别名时按 DNS 服务商规则配置 CNAME。不要把 A 记录写成手机的私网地址或 127.0.0.1，也不要把管理面板 9090 一并公开。

在域名服务商控制台操作时：选中你拥有的域名 → DNS / 解析管理 → 添加记录。以 www 子域名为例：

TTL 可以先用服务商默认值。主域名常用 @，具体按服务商说明；同一个名称不要同时配置 CNAME 与 A/AAAA。记录值不填写 http://、路径、冒号端口。上表只表示记录格式，不能替代真实入口的配置。

保存后，可在电脑用下面的命令查询公共解析；将 www.YOUR_DOMAIN 替换为你的真实完整域名：

nslookup www.YOUR_DOMAIN

确认解析结果是公网入口的地址，再通过实际 HTTP/HTTPS 请求验证网站。解析尚未更新时，先核对权威记录和 TTL，不反复重建手机网站。只有公网入口已经正确配置网站、证书与隧道时，https://你的真实域名 才能正常访问。

使用独立服务器入口时，还必须把网站流量经受控隧道送到手机，并保留正确的 Host。可以将手机网站经 SSH 反向转发到自有入口服务器的回环高位端口，再由该服务器的 Nginx 80/443 网站配置代理；这一部分涉及入口服务器账号、SSH 转发策略、证书及网络，不是当前面板已经自动完成的功能。

公网正式发布前，需要单独确认实际域名、入口、证书、隧道恢复、网站程序安全与 Android 长期稳定结果。不要通过关闭 SELinux、禁用热保护或安装不明“一键穿透面板”解决可达性问题。

12. 面板设置、日常维护与恢复

“面板设置”可修改面板监听端口、单文件上传上限、批次上传总量。端口允许1024–65535；保持原本机/局域网访问范围。保存前检测与网站端口冲突及实际监听占用，冲突会拒绝保存。保存后面板重新监听并注销会话，约12秒跳转新入口，请重新登录；网站、PHP和数据库继续运行。

修改端口后，局域网使用手机IP加新端口。USB/SSH转发及外部监控需同步更新，例如改为9091后在电脑执行 adb forward tcp:9091 tcp:9091。端口设置不会自动修改路由器或系统防火墙。上传默认2/32 MiB，SQL导入遵循单文件上限；过大的批次会增加手机存储、内存及传输耗时。

面板重启会注销浏览器会话，但不应停止 Nginx、FPM、MariaDB。停止网站服务前注意影响对应网站，面板自己不依赖 PHP 或数据库维持登录。

本机管理员密码重置：在 Termux 运行下面这一条命令，等待提示后逐项输入，不把多条交互命令一次粘贴进隐藏密码输入中。

bash "$HOME/termux-panel/scripts/reset-password.sh"

先输入确认单词 PASSWORD，再输入新密码两次。当前面板密码最低10字节；新版脚本只有用新密码实际 HTTP 登录得到200后才报告成功。密码不要发到聊天或写进 shell 命令历史。

数据库逻辑备份用面板页面；面板状态和站点内容冷备份用 scripts/backup.sh，先停止面板及站点写入，再按脚本预检确认。冷备份含敏感配置，不能作为公开下载文件。详细恢复、卸载、二进制回滚和事务恢复见 docs/operations.md。

Root 不是基本功能的前提。当前 Boot 和独立 HTTP 看门狗默认未启用；用户此前选择将 24 小时、72 小时、7 天及重启恢复测试留到后续，尚不能保证 Android 永久保活。Play 渠道 Boot 功能与其它渠道插件存在差异，按 docs/android15-keepalive.md 核对。

13. 常见问题

14. 快速命令索引

以下在手机 Termux 执行，均只读：

curl --noproxy '*' http://127.0.0.1:9090/healthz
sv status "$PREFIX/var/service/termux-panel"
sv status "$PREFIX/var/service/tpanel-nginx"
sv status "$PREFIX/var/service/php-fpm"
sv status "$PREFIX/var/service/tpanel-mysqld"

服务名字以当前诊断和运行手册为准，缺失时不要创建空脚本冒充。完整只读诊断会在指定项目目录写报告：

cd "$HOME/termux-panel"
bash scripts/doctor.sh ./diagnostics

电脑检查当前 USB 转发：

.\adb-fastboot\adb.exe forward --list

需要修改服务、开放入口、恢复数据库或重启设备时，先明确目标和变更；页面不会通过“查看端口”自动执行这些操作。