From 7dcbc960a7d68a8d17998f311d65387ec5f6312e Mon Sep 17 00:00:00 2001 From: zhang-pu <69795881+zhang-pu@users.noreply.github.com> Date: Sat, 13 Jun 2026 16:31:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20CHANGELOG.md=20(v1.3.0=20?= =?UTF-8?q?=E2=86=92=20v1.3.41=20full=20history)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 492 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 492 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a1e8d96 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,492 @@ +# TPanel 变更日志（CHANGELOG） + +> **作者**: Zhang Pu +> **官网**: https://tpanel.cn +> **GitHub**: https://github.com/zhang-pu/tpanel +> **协议**: MIT +> **发布周期**: 紧急修复为主，无固定周期 +> **版本约定**: v1.3.X 中，X 是累计迭代号；只有经过实机验证的稳定版会发 GitHub Release +> **本日志涵盖**: v1.3.0 (2026-05-30) → v1.3.40 (2026-06-12) + +--- + +## 📦 v1.3.40 — 2026-06-12 【正式发布】 + +> **重点**: phpMyAdmin 自动登入 + 装包自愈 + dpkg 二次校验 + +### 🐛 关键修复 + +1. **phpMyAdmin 装包失败后 files_exist 误判** + - dpkg 标记 `Status: install ok installed` 但 `/usr/share/phpmyadmin` 实际 missing（partial install） + - 前端 status 报"已装"但实际 502 / 找不到目录 + - 修：加 `dpkg -V phpmyadmin` 二次校验 + 自动 `apt-get install --reinstall` + +2. **setup_phpmyadmin_nginx 缺 self-heal** + - 找不到 pma 目录就 silently return False，没给运维任何提示 + - 修：开头加 `dpkg -V` 探测 + `apt-get install --reinstall` 自动重装 + - 修：加 `ss -tln | grep :9000` 探测 PHP-FPM listen，不通就 warn 日志（不再 silent 502） + +3. **`/api/phpmyadmin/token/` 端点缺失**（v1.3.34 前端依赖） + - 前端点数据库名时调 `/api/phpmyadmin/token/` 拿 5 分钟 HMAC token + - 后端 main.py 一直没实现这个端点 → 404 → 前端 `window.open` 不执行 → 用户点"没反应" + - 修：新增 `api_phpmyadmin_token` + `api_phpmyadmin_signon` 端点 + +4. **api_phpmyadmin_signon 写 bridge.json Permission denied** + - `/usr/share/phpmyadmin` 是 root 755，tpanel 用户没写权限 + - 修：用 `sudo mv /tmp/bridge.json` + `sudo chmod 644` 两步 + +5. **CONFIG 缺 SECRET_KEY** + - HMAC token 签发需要密钥，config.py 没有 + - 修：启动时 `secrets.token_hex(32)` 随机生成 64 字符 hex + +### ✨ 新增功能 + +1. **phpMyAdmin 自动登入**（点数据库名 → 直接进 pma） + - HMAC token 5 分钟有效，绑 db_id + - signon 端点写 `bridge.json`（db_user/db_pass/ts） + - nginx 8443 反代 + 8400 PHP-FPM listen + - `tpanel-bridge.php` 桥接 session → pma 自动用 db_user 登入 + - `/etc/phpmyadmin/config.inc.php` 启用 `config` auth，读 signon data 自动填账号 + +### 📝 教训 + +- 永远别让 dpkg 静默失败——必须用 `dpkg -V` 二次校验 +- v1.3.34 前端加了 token 端点，但后端 main.py 一直没合并过来——半年才被发现 +- 写装包脚本必须在干净机器上真跑一遍（这次踩坑 6/10 装包 partial，6/12 才暴露） + +--- + +## 📦 v1.3.39 — 2026-06-11 【开发版，未发 release】 + +### 🐛 修复 + +1. **软件卸载改用 `purge` 而非 `remove`** + - `remove` 保留配置（`/etc/nginx/sites-enabled/*.conf` 不删） + - 改 `purge` 完全删干净 +2. **加 on_complete 钩子到卸载流程** + - 卸载 PHP 后自动 reload nginx + 改 8848 配置 +3. **task_manager dpkg -s 误判修复** + - `dpkg -s` 对 `deinstall ok config-files` 状态返 0，会误判"已装" + - 加 explicit check 区分 installed / config-files + +--- + +## 📦 v1.3.38 — 2026-06-11 【开发版，未发 release】 + +### 🐛 修复 + +1. **fastcgi_pass 端口按 PHP 版本动态选** + - 之前硬编码 `127.0.0.1:9000`，多 PHP 版本时 8.1/8.2/8.3 混用 + - 修：ssl_manager.py 写 nginx conf 时按 db 的 php_version 字段选对应端口 +2. **nginx reload 在 file change 事件触发** + - 修：inotify 等价实现（轮询 mtime） + +--- + +## 📦 v1.3.37 — 2026-06-10 【开发版，未发 release】 + +### 🐛 修复 + +1. **on_complete 钩子无 Flask request context** + - 后台线程跑钩子时 `request.remote_addr` 不可用 → 报 AttributeError + - 修：钩子里 `try/except`，None 当 fallback +2. **write_log 接受 None ip** + - 部分场景 ip 是 None 时报 TypeError + +--- + +## 📦 v1.3.36 — 2026-06-09 【开发版，未发 release】 + +### ✨ 新增 + +1. **get_installed_php_versions() 函数** + - system.py 新增，扫描 `/usr/bin/php*` + dpkg -l + - 前端创建站点时只列已装 PHP（避免选错导致 502） + +2. **建站时 PHP 版本校验** + - 前端二次校验（即使后端也校验了） + - 未装的 PHP 选项 disabled + - 防止用户选 PHP 5.6 装了一半发现 FPM 没起来 + +--- + +## 📦 v1.3.35 — 2026-06-08 【正式发布】 + +> **重点**: 文件管理权限调整 + +### 🐛 修复 + +1. **lscpu 在容器/Docker 无 "Model name" 行导致 Unknown CPU** + - 仪表盘显示 `Unknown CPU` + - 修：`/proc/cpuinfo` fallback 读 model name +2. **chmod UI 修复**（前端） + - 数字校验、3 位 0-7 限制、rwx 实时预览 + - 暴露 `parsePermMode` 处理 0o755 八进制 vs '755' 字符串两种输入 + +### 发布 + +- GitHub Release: `v1.3.35` 文件管理权限调 +- 源码包: `/work/tpanel-v1.3.35-source.zip` + +--- + +## 📦 v1.3.34 — 2026-06-07 【开发版，未发 release】 + +### ✨ 新增 + +1. **phpMyAdmin Signon 模式前端支持** + - 点数据库名 / 🐘 按钮调 `_openPmaWithAutoLogin(dbId, dbName)` + - 拿 5 分钟 HMAC token → 跳 `/api/phpmyadmin/signon?token=...&db=1` + - 跳 `/tpanel-bridge.php?token=...&db=1` → 302 到 pma + - **后端 main.py 当时没实现 token + signon 端点**（直到 v1.3.40 才补） + +2. **改数据库密码前端 UI** + - 🔑 按钮 → 输入新密码 → 调 `/api/databases//password` + - 后端 v1.3.34 同时实现 change_db_password + +--- + +## 📦 v1.3.33 — 2026-06-08 【正式发布】 + +### 杂项 + +- 一些 UI 调整 +- cron manager 优化 + +### 发布 + +- GitHub Release: `v1.3.33` + +--- + +## 📦 v1.3.30 — 2026-06-08 【正式发布】 + +> **重点**: 一键安装脚本 v1.3.30（合并 v1.3.22 ~ v1.3.29 累积修复） + +### 🐛 合并自 1.3.22 ~ 1.3.29 + +- v1.3.22 移动端侧边栏 ☰ 按钮 +- v1.3.23 phpMyAdmin URL 不再硬编码 127.0.0.1 +- v1.3.24 SSL .well-known 查 sqlite 拿真 site_path +- v1.3.25 SSL 申请走任务流 + SSE 进度框 +- v1.3.26 站点类型 php|static + 静态 index.html +- v1.3.27 SSE query string 传 token（EventSource 不能自定义 header） +- v1.3.28 add Sury PHP 源 +- v1.3.29 on_complete 钩子自动配 PHP-FPM listen + 批量重写 nginx conf 按 PHP 版本 + +### 发布 + +- GitHub Release: `v1.3.30` +- 官网: https://tpanel.cn/install.sh 同步更新 + +--- + +## 📦 v1.3.14 — 2026-06-07 【正式发布】 + +> **重点**: `static-check.py` 静态分析工具 + +### 🐛 问题 + +v1.3.10 ~ v1.3.13 四轮迭代反复「装机后才发现」—— sandbox 里没 docker/systemd，不能跑完整 install.sh。但**所有 4 轮 bug 都是同一个模式**：「双向闭环」一边配一边调用漏一边。 + +### ✨ 解法 + +写个 `static-check.py` 静态分析工具，从源码挖双向闭环 bug： + +1. 高危命令 `_run` 裸调（查 `_run(['cmd', ...]` 中 cmd 是否在 DANGEROUS_CMDS 且无 sudo） +2. install.sh sudoers 双向闭环 +3. 前端 `/api/` 路由 vs main.py `@app.route` 一致性 +4. import 模块存在性 +5. 版本号一致性 +6. Nginx 端口 vs main.py 监听端口 +7. on_complete 钩子函数定义存在 +8. phpMyAdmin 反代路径探测逻辑完整 +9. Nginx SSE location 含 1800s timeout +10. sudoers 含 `!requiretty` + +### 🐛 首跑挖出 v1.3.14 候选 bug + +`ssl_manager.py` 108/112/291/295 行裸调 nginx（v1.3.11 漏改）—— 已修复。 + +### 发布 + +- `/work/tpanel-v1.3.14-source.zip` (79KB) +- `/work/tpanel-static-check.py` (16KB, md5=a87524aebffff4e81015ef4249bf3c9c) +- `/work/tpanel-v1.3.14-docs.zip` (16KB) + +### 📝 教训 + +写 install.sh 必须在干净 VPS 上真跑一遍，5 分钟的事。考虑加 install-test 自动化测试。 + +--- + +## 📦 v1.3.13 — 2026-06-07 【正式发布】 + +### 🐛 修复 + +1. **sudo NOPASSWD 实际不生效 → `sudo: a terminal is required to read the password`** + - v1.3.11 硬编码 `/usr/sbin/useradd` 在某些 Debian minimal 镜像上不对 + - 被 `Defaults requiretty` 全局设置挡住 NOPASSWD + - 修：install.sh 用 `command -v` 动态探测命令路径 + - 修：sudoers 加 `Defaults:tpanel !requiretty` 关键声明 + - 修：`visudo -c -f` 语法验证 + - 修：装完立刻试跑 NOPASSWD + - 提供 `tpanel-fix-sudo.sh` 紧急补丁脚本 + +2. **提供 `tpanel-install-test.sh` 装完自检脚本**（6 节检查） + - 系统基本 / sudoers NOPASSWD / Nginx SSE / phpmyadmin 反代 / 端到端 API / 服务健康 + +--- + +## 📦 v1.3.12 — 2026-06-07 【正式发布】 + +### 🐛 修复 + +1. **SSE 连接断开**（用户装机实测） + - Nginx 默认 `proxy_read_timeout 60s`，apt install/upgrade 静默 30s+ 是常态 + - 60s 到点 Nginx 主动断开代理，浏览器 EventSource 看到"连接断开" + - 修：install.sh Nginx 配置为 `/api/tasks//stream` 加专用 location + - `proxy_read_timeout 1800s` + `proxy_buffering off` + `X-Accel-Buffering: no` + `proxy_cache off` + - 提供 `tpanel-fix-sse.sh` 紧急补丁 + +--- + +## 📦 v1.3.11 — 2026-06-07 【正式发布】 + +### 🐛 修复 + +1. **全新装机新建站点报 `useradd: Permission denied`** + - v1.3.10 install.sh 只为 mysql 授权 sudoers + - system.py 中 useradd/userdel/chown/chmod/nginx -s reload 全是裸调 + - 新建站点第一步创建系统用户就 100% 失败 + - 修：install.sh 新增 `/etc/sudoers.d/tpanel-admin` + - NOPASSWD 授权 useradd/userdel/usermod/chown/chmod/nginx/systemctl + - `/usr/sbin/` + `/usr/bin/` 都列上（Debian/CentOS 路径不同） + - 修：system.py 全面加 sudo 前缀 + +### 📝 教训 + +凡是要 root 权限的命令（useradd/chown/nginx 等），system.py 写了 sudo 必须配 sudoers；反过来，install.sh 加 sudoers 必须 system.py 真的调了 sudo——两边要对得上 + +--- + +## 📦 v1.3.10 — 2026-06-07 【正式发布】 + +> **重点**: phpMyAdmin on_complete 钩子 + 软件市场 + 任务管理 + +### 🐛 修复 + +1. **phpMyAdmin 装完无反代 → 点 🐘 死循环 confirm** + - v1.3.10 装完 phpMyAdmin 后没有自动写 Nginx 8443 反代配置 + - `/api/phpmyadmin/status` 永远返回 `nginx_ok=false` + - 前端 `setTimeout(..., 1000)` 跳走再调 status 又触发 confirm + - 修：`setup_phpmyadmin_nginx` 函数实现 + on_complete 钩子 + +2. **软件市场 + 任务管理** + - software 表 + tasks 表 + - `create_task(name, cmd, on_complete=...)` 通用接口 + - 实时进度通过 SSE 推前端 + - 装完自动调 on_complete 钩子 + +3. **预检环境** + - `create_site` 前检查：磁盘空间 / 内存 / nginx 状态 + +### 发布 + +- `/work/tpanel-v1.3.10-source.zip` (61KB, md5=1b6b3ef02ce05ce6a609899d71b3ed0d) +- tpanel.cn/install.sh 同步更新 + +--- + +## 📦 v1.3.9 — 2026-06-06 【正式发布】 + +> **重点**: super release，合并 6/6 全部修复 + +### 🐛 关键修复 + +1. **登录后必须强制刷新才能看到后台**（v1.3.8 时代就有，**用户实测发现**） + - 根因：`showLogin()` 用 `document.body.innerHTML = '...'` 整个重写 body + - 把后台骨架（aside.sidebar + main.main）全部销毁 + - 结果：login() 成功后 `initApp() → setupNav()` 找不到 `.nav-item[data-page]` + - `loadDashboard()` 静默失败（getElementById 返 null 被 try/catch 吞掉） + - 现象：登录后页面卡在登录页，必须 Ctrl+Shift+R 才能进后台 + - **修法**：登录页改独立 `
`，后台骨架包一层 `
` + - `showLogin/hideLogin` 改 display 切换 + - `logout()` 也改用 showLogin() 而非 location.reload() + +### 📝 教训 + +- **永远别 innerHTML 重写 body**；前端 SPA 登录前后页面元素应该一直在 DOM 里 +- **发布前必跑一次完整登录流程**，API 200 不等于 UI 正常 + +### 发布 + +- `/work/tpanel-v1.3.9-source.zip` (49KB, md5=69b461098fc2429533dec918f976f0ad) + +--- + +## 📦 v1.3.8 — 2026-06-05 【正式发布】 + +> **重点**: 8 个隐藏 bug 一次性修 + +1. **zip 魔数校验**：用 `grep -q "PK\x03\x04"`（grep 文本模式不解析 \x），所有合法 zip 都被误判为 404 HTML + - 改用 `od -An -tx1 -N4` + hex 字符串比较 +2. **解压漏复制**：只 `cp backend/ frontend/`，没复制根目录的 `requirements.txt`、`.gitignore` 等文件 +3. **`/etc/nginx/tpanel` 权限**：config.py import 时就 `os.makedirs('/etc/nginx/tpanel')`，tpanel 用户无权限 + - install.sh 补上 `mkdir -p && chown tpanel:tpanel` +4. **systemd ExecStart 没传端口**：ExecStart 写的是 `python main.py`（没传参） +5. **前端 JS 2 处语法错误**（v1.0.0 时代就有，从未暴露） +6. **PHP-FPM 完全没装**（最大坑！所有建 PHP 站的人全 404） + - install.sh 加 `php8.2-fpm + 扩展` 自动装 +7. **PHP-FPM unix socket 在 systemd 环境失效** + - 改用 TCP `127.0.0.1:9000` +8. **MySQL/MariaDB 完全没装 + shell=True SQL 注入**（最危险！） + - install.sh 加 mariadb-server + sudoers + - system.py create_mysql_db/delete_mysql_db 改用 subprocess list + sudo + regex 校验 + +### 📝 教训 + +写 install.sh 必须在干净 VPS 上真跑一遍，5 分钟的事。考虑加 install-test 自动化测试。 + +--- + +## 📦 v1.3.4 — 2026-06-05 【开发版，未发 release】 + +3 个 install.sh 隐藏 bug 修复（同 v1.3.8 的 1/2/3 项） + +--- + +## 📦 v1.3.3 — 2026-06-05 【开发版，未发 release】 + +小修补。 + +--- + +## 📦 v1.3.2 — 2026-06-05 【正式发布】 + +### 🐛 致命 bug + +v1.3.1 的 install.sh 用 `grep -q "PK\x03\x04"` 校验 zip 魔数，但 grep 文本模式不解析 \x 转义，所以**永远拒绝所有 zip**，5 个下载源全挂。 + +### 修法 + +改用 `od -An -tx1 -N4` + hex 字符串比较（`504b0304`），端到端测试通过。 + +### 📝 教训 + +写校验代码必须真实验证，不能"看起来对"。 + +--- + +## 📦 v1.3.1 — 2026-06-04 【正式发布】 + +### ✨ install.sh 健壮性大幅提升（9.5KB） + +- 4 个下载源自动回退：Release → latest → tag → main 分支 +- zip 文件魔数校验（PK\x03\x04），自动识别 404 HTML 不再解压报错 +- 本地兜底：自动扫描 `/tmp/tpanel*.zip` +- 修复：main.py 中 `get_panel_domain` 在空配置下的 500 错误 + +### 发布 + +- GitHub Release: `v1.3.1` +- tpanel.cn/install.sh 同步更新 +- 源码包: `/work/tpanel-v1.3.1-source.zip` (47KB) + +--- + +## 📦 v1.3.0 — 2026-05-30 【稳定版】 + +首次正式发版。Python Flask + SQLite + 原生 HTML/CSS/JS 单文件前端。 + +### 已实现 + +- 网站管理（增删改查 + nginx conf 自动写） +- 数据库管理（MariaDB） +- SSL 证书（Let's Encrypt 申请 / 续期） +- 备份（本地 + 远程 rsync） +- 文件管理（上传 / 编辑 / 权限） +- 定时任务（cron 增删 + 立即执行） +- 安全（每日 03:00 自动 apt upgrade + UFW 防火墙） +- 域名绑定（限制后台访问来源） + +### 设计目标 + +- 单 VPS 80/443 端口默认站 + 多个 vhost +- 一键安装：`wget -O install.sh https://tpanel.cn/install.sh && bash install.sh` +- 默认账号 `admin / tpanel.cn`，服务路径 `/opt/tpanel` + +--- + +## 📋 待办 / 路线图 + +## 📦 v1.3.41 — 2026-06-13 【正式发布】 + +> **重点**: Dashboard 数字色修复 + SSL 证书同步 + PHP 动态下拉 + +### 🐛 关键修复 + +1. **Dashboard 数字色修复** + - v1.3.40 把 `.stat-card .value` 颜色写死 `#fff`，light 主题（粉卡片）下完全看不见 + - 改成 `var(--text)` 跟随主题（dark 主题显示浅色，light 主题显示深色） + - 受影响：📁 网站总数 / 🗄️ 数据库 / 💾 备份状态 / 🔐 安全更新 4 个数字 + +2. **数据库页面图标错位** + - `.data-table td` 加 `vertical-align: middle` + - 30px 高的图标按钮跟 13px 文字 baseline 不对齐 + - 修复后 4 列完美居中 + +3. **SSL 证书同步按钮（新功能）** + - 加 `/api/ssl/sync` API + 前端 `🔄 同步证书库` 按钮 + - 扫 `/etc/letsencrypt/live/` 重建 `ssl_certs` 表 + - 解决 v1.3.40 升级时 `apply_letsencrypt` 漏写数据库的 bug + - 适用场景：数据库丢失 / 不一致 / 跨机迁移 + +4. **PHP 版本下拉框优化** + - 加 `/api/system/php-versions` API + - 前端动态拉已装版本：已装 ✓ / 未装灰显 + - 选中未装版本时红字提示「⚠️ 新建站点时会 502」+ 跳软件市场安装链接 + - 默认值改成 8.2（v1.3.40 默认 8.1 但很多镜像没装 8.1） + +### 🆕 新文件 + +- `backend/ssl_sync.py`（SSL 证书同步工具） + +### 📊 验证 + +- 端到端：API 返回 `{"added":0,"updated":3,"skipped":0,"errors":[]}` ✅ +- 静态分析：py_compile 通过 + JS 括号配对 ✅ +- 前端：3 处新代码（按钮 + 函数 + 调用）✅ +- 后端：5 个新路由/函数（`api_ssl_sync`, `api_system_php_versions` 等）✅ + +--- + +### v1.3.41+ 候选 + +- **自动注入 pma Signon session 优化**：当前靠 `/tmp/tpanel_signon_data.json` + config auth 凑合 + - 下个版本尝试 pma 5.2 原生 `SignonSession` 模式（不用 config auth） +- **多 PHP 版本切换前端**（用户能选 7.4/8.0/8.1/8.2/8.3/8.4） +- **Node.js 支持**（类似 PHP 装包） +- **nginx 日志查看器**（v1.3+） +- **TPanel 密码修改功能**（前端已占位，后端缺实现） +- **打印机故障诊断**（图片识别问题待解决） + +### 商业化（Freemium 模式） + +- 免费版：全功能使用，页面必须保留作者链接（Powered by TBlog/TPanel） +- 专业版：付费去除链接，解锁高级功能（多站点管理、高级备份、技术支持） +- 技术方案：激活码许可证系统（类似 WordPress/JetBrains） + +--- + +## 🔖 版本号约定 + +- 末位 +1 = 紧急修复（任何时机） +- 末位 +2 = 累积新功能（每月） +- 主版本不动（v1.3 → v2.0 是大重构） +- 注释里 `# v1.3.X` 必标（这个 changelog 才有依据） + +--- + +**最后更新**: 2026-06-13 16:30 CST +**编辑**: Zhang Pu via OpenClaw MiniMax-M3 (v1.3.41 push)