tpanel/SPEC.md

T面板 - 规格说明书

1. 项目概述

• 名称：T面板（tpanel）
• 官方网址：https://tpanel.cn
• 定位：轻量级 Linux 网站管理面板，聚焦建站核心功能
• 目标用户：个人站长、中小型网站管理者

2. 核心功能

2.1 网站管理

• 创建站点（绑定域名、选择PHP版本、设置目录）
• 删除站点（含数据确认）
• 站点列表（域名、状态、创建时间、备份状态）
• 站点起停（nginx reload/restart）
• 流量统计（nginx access log 解析）

2.2 SSL 证书

• Let's Encrypt 免费证书申请（HTTP验证）
• 证书自动续期（systemd timer 触发 certbot）
• 一键部署到站点
• 证书状态监控（剩余天数）

2.3 数据库管理

• 创建 MySQL 数据库 + 用户
• 删除数据库
• phpMyAdmin 一键安装（可选）
• 数据库列表（名称、大小、字符集）

2.4 备份系统

• 本地备份（tar + mysql dump）
• 远程备份（rsync 到另一台服务器）
• 定时备份（cron 表达式）
• 下载备份文件
• 恢复备份

2.5 安全功能

• 系统更新（apt-get security update）
• 站点数据隔离（Linux 用户分离）
• SSH 密钥管理（可选）
• 防火墙规则（UFW）
• 异常登录告警
• 自动漏洞修复（cron 定期执行）

2.6 文件管理

• 在线文件浏览
• 上传文件（压缩包自动解压）
• 编辑配置文件（高亮）
• 权限管理

3. 技术架构

3.1 目录结构

/opt/tpanel/
├── backend/
│   ├── main.py              # Flask 入口
│   ├── system.py            # 系统操作（nginx/mysql/backup）
│   ├── site.py              # 站点管理
│   ├── database.py          # 数据库管理
│   ├── ssl.py               # SSL 管理
│   ├── firewall.py          # 防火墙
│   ├── security.py          # 安全更新
│   ├── config.py            # 配置读写
│   └── utils.py             # 工具函数
├── frontend/
│   ├── index.html           # 主面板
│   ├── css/
│   ├── js/
│   └── assets/
├── data/                    # SQLite 数据库
├── sites/                   # 站点目录 /www/tpanel/sites/
├── backups/                 # 备份目录
├── logs/                    # 日志
├── ssl/                     # SSL 证书目录
└── config/                  # Nginx 配置 /etc/nginx/tpanel/

/etc/systemd/system/tpanel.service
/etc/nginx/tpanel-api.conf   # Nginx 反向代理

3.2 数据库表

-- 管理员账号
CREATE TABLE admin (
    id INTEGER PRIMARY KEY,
    username TEXT NOT NULL UNIQUE,
    password_hash TEXT NOT NULL,  -- bcrypt
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_login DATETIME
);

-- 站点
CREATE TABLE sites (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    domain TEXT NOT NULL UNIQUE,
    site_user TEXT NOT NULL UNIQUE,   -- Linux 用户名
    site_path TEXT NOT NULL,
    php_version TEXT DEFAULT '8.1',
    status TEXT DEFAULT 'running',     -- running/stopped
    ssl_enabled INTEGER DEFAULT 0,
    ssl_cert_path TEXT,
    ssl_key_path TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 数据库
CREATE TABLE databases (
    id INTEGER PRIMARY KEY,
    site_id INTEGER REFERENCES sites(id),
    name TEXT NOT NULL UNIQUE,
    db_user TEXT NOT NULL UNIQUE,
    db_pass TEXT NOT NULL,
    charset TEXT DEFAULT 'utf8mb4',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 备份记录
CREATE TABLE backups (
    id INTEGER PRIMARY KEY,
    site_id INTEGER REFERENCES sites(id),
    type TEXT DEFAULT 'local',       -- local/remote
    file_path TEXT,
    size INTEGER,
    status TEXT DEFAULT 'success',   -- success/failed
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- SSL 证书
CREATE TABLE ssl_certs (
    id INTEGER PRIMARY KEY,
    site_id INTEGER REFERENCES sites(id),
    domain TEXT NOT NULL,
    cert_path TEXT NOT NULL,
    key_path TEXT NOT NULL,
    expire_date DATETIME,
    auto_renew INTEGER DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 定时任务
CREATE TABLE cron_jobs (
    id INTEGER PRIMARY KEY,
    site_id INTEGER REFERENCES sites(id),
    name TEXT NOT NULL,
    schedule TEXT NOT NULL,          -- cron 表达式
    command TEXT NOT NULL,
    enabled INTEGER DEFAULT 1,
    last_run DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 安全日志
CREATE TABLE security_logs (
    id INTEGER PRIMARY KEY,
    event_type TEXT NOT NULL,
    details TEXT,
    ip TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 设置
CREATE TABLE settings (
    key TEXT PRIMARY KEY,
    value TEXT
);

3.3 安全机制

1. 站点隔离：每个站点一个 Linux 用户，Home 目录即网站根目录，禁 shell
2. 最小权限原则：MySQL 用户权限精确到站点数据库
3. CSRF 防护：所有 POST 请求带 token 验证
4. 命令白名单：仅允许预设的 shell 命令，无 shell 注入
5. HTTPS：面板强制 HTTPS，API 只能用 Token 认证
6. 文件上传限制：仅允许 .zip/.tar.gz 上传，自动解压到站点目录
7. 日志审计：所有操作写 security_logs
8. 自动修复：每日 3:00 执行 apt-get update && apt-get upgrade -y

3.4 防火墙规则（UFW）

• 默认只开放 22（SSH）、80（HTTP）、443（HTTPS）
• 管理面板端口（例如 8848）仅限 localhost 访问
• Nginx 反向代理到面板后端

4. 面板设计

4.1 界面风格

• 风格：深色主题 + 绿色点缀（科技感、安全感）
• 字体：JetBrains Mono（代码）+ Inter（界面）
• 配色：主色 #22c55e（绿色），背景 #0f172a（深蓝黑），卡片 #1e293b

4.2 布局

┌─────────────────────────────────────────────────┐
│  [Logo] T面板          [站点数] [状态] [安全更新] │
├─────────────────────────────────────────────────┤
│                                                 │
│  [仪表盘] [网站] [数据库] [SSL] [备份] [安全]    │
│                                                 │
│  ┌─────────────────────────────────────────┐   │
│  │              内容区域                     │   │
│  └─────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

5. API 设计

5.1 认证

POST /api/auth/login    { username, password }
POST /api/auth/logout
GET  /api/auth/check    (Header: Authorization: Bearer <token>)

5.2 站点

GET    /api/sites              列表
POST   /api/sites              创建 { domain, php_version, path }
GET    /api/sites/:id          详情
PUT    /api/sites/:id          更新 { status, ssl }
DELETE /api/sites/:id          删除
POST   /api/sites/:id/start     启动
POST   /api/sites/:id/stop      停止
POST   /api/sites/:id/backup    触发备份

5.3 数据库

GET    /api/databases
POST   /api/databases          创建 { site_id, name, user, pass }
DELETE /api/databases/:id

5.4 SSL

POST /api/ssl/apply             { site_id, domain }
GET  /api/ssl/certs             列表
POST /api/ssl/renew/:id         续期

5.5 备份

GET  /api/backups               列表
POST /api/backups               创建 { site_id, type }
GET  /api/backups/:id/download
POST /api/backups/:id/restore
DELETE /api/backups/:id

5.6 安全

GET  /api/security/logs          安全日志
POST /api/security/update       执行系统更新
GET  /api/security/status       安全状态（已安装更新数、漏洞数）

6. 安装流程

6.1 一键安装脚本

wget -O install.sh https://tpanel.cn/install.sh
bash install.sh

安装脚本做的事情：

1. 检测系统（Debian 10+ / Ubuntu 20.04+）
2. 安装 Nginx、MySQL、Python3、certbot
3. 创建 tpanel 用户和目录
4. 初始化 SQLite 数据库
5. 配置 systemd 服务
6. 配置 Nginx 反向代理
7. 申请 Let's Encrypt 面板证书
8. 启动服务

6.2 默认端口

• 面板访问：https://localhost:8848 （仅本地访问）
• 通过 Nginx 反代到域名，例如 https://tpanel.cn

7. 版本规划

v1.0.0（首发）

• 站点 CRUD
• MySQL 数据库 CRUD
• Let's Encrypt SSL
• 本地备份
• 系统安全更新

v1.1.0

• 远程备份（rsync）
• 定时任务
• 文件管理

v1.2.0

• Cron 表达式验证
• 远程 rsync 备份 + 恢复
• 连接测试工具
• 备份统计面板

v1.3.0（待开发）

• 多 PHP 版本切换
• Node.js 支持
• 日志查看器（nginx access/error log）

8. 开源协议

MIT License

9. 作者

• 作者：Zhang Pu
• 网站：https://zhangpu.dev
• 面板官网：https://tpanel.cn