jhp.studio站点结构说明
站点结构说明
给想自己改动站点的你看的。核心站点只有 14 个文件、约 1100 行 PHP/JS， 玩法和工具是另外一批独立页面，删掉也不影响文档站本身。
目录树
wwwroot/ ← 网站根目录（主机面板里叫 3Wroot）
├── index.php 首页（渐变 Hero + 新闻速递 + 天气 + 文档列表）
├── doc.php 阅读页（三栏布局 + 文末每日速递）
├── search.php 搜索接口（返回 JSON）
├── news.php 每日新闻速递（完整列表）
├── weather.php 天气页（IP 定位 + 7 天预报）
├── about.php 关于页（介绍 / 技能 / 时间线 / 友链）
├── rss.php RSS 订阅输出（docs 最新 20 篇）
├── config.php 配置：站名、密码、阅读速度
├── lib/
│ ├── Parsedown.php Markdown 渲染库（第三方，别改）
│ └── site.php 核心函数库
├── assets/
│ ├── style.css 站点全部样式
│ ├── search.js 搜索框 + 目录滚动高亮
│ ├── weather.js 天气公共模块（定位 + Open-Meteo）
│ └── logo.png 站点图标（favicon + 顶栏 Logo，26px 内联限高）
├── admin/
│ ├── index.php 后台：登录 + 编辑器界面
│ └── save.php 后台接口：读/存/删/建目录
├── docs/ 你的所有文档（侧边栏 = 这里的目录结构）
│ ├── guide/ 使用教程
│ ├── play/ 玩法中心说明
│ ├── tools/ 工具中心说明
│ ├── cpp/ C++ 笔记
│ └── suibi/ 随笔
├── play/ 【玩法中心】
│ ├── index.html 玩法中心首页（卡片墙）
│ ├── piano/ 电脑钢琴
│ ├── drum-machine/ 鼓机 · 节奏音序器
│ ├── pixel-art/ 像素画板
│ ├── algo-visual/ 算法可视化动画
│ ├── retro-games/ 怀旧小游戏合集
│ ├── gomoku/ 五子棋 AI（三档难度）
│ ├── tetris/ 俄罗斯方块
│ ├── lucky-wheel/ 抽奖转盘
│ └── clockwork-city/ 发条巨城（index.html + theme.css + 7 个 .js，多文件 + 本地存档）
└── tools/ 【工具中心】
├── index.html 工具中心首页（卡片墙）
├── dev-tools/ 开发工具箱
├── typing-test/ 打字测速
├── qr-code/ 二维码生成器（含本地二维码库）
├── pomodoro/ 番茄钟 + 白噪音
├── calc/ 科学计算器
├── diff/ 文本差异对比
├── world-clock/ 世界时钟
└── password/ 密码生成器核心文件（文档站本身）
| 文件 | 行数 | 职责 |
|---|---|---|
index.php |
59 | 渲染首页（Hero + 新闻速递 + 联系 + 天气 + 全部文档） |
doc.php |
79 | 读 md → 渲染 → 字数/时长 → TOC → 文末每日速递 |
search.php |
6 | 接收 ?q=，返回搜索结果 JSON |
news.php |
30 | 每日新闻完整列表（按天分组） |
weather.php |
105 | 天气页（IP 定位 + 城市搜索 + 7 天预报） |
about.php |
58 | 关于页（介绍 / 技能 / 时间线 / 友链，占位内容可改） |
rss.php |
46 | 扫 docs/ 输出 RSS 2.0（最新 20 篇） |
config.php |
33 | 站名、密码哈希、联系方式、上传限额 |
lib/site.php |
323 | 目录树、字数统计、TOC、搜索、新闻抓取与缓存、SEO、安全校验、页头页尾 |
lib/Parsedown.php |
— | Markdown → HTML（第三方） |
assets/style.css |
249 | 站点全部样式（改配色改这里） |
assets/search.js |
60 | 搜索下拉、Ctrl+K、目录高亮 |
assets/weather.js |
99 | 天气公共模块（ip-api 定位 + Open-Meteo，免 key） |
admin/index.php |
171 | 登录 + Vditor 编辑器 + 文档树 + 删除分类 |
admin/save.php |
90 | 写文件、读文件、删除、建目录、删分类（递归） |
assets/logo.png |
— | 站点图标（favicon + 顶栏 Logo，26px 内联限高） |
玩法 / 工具页面
| 文件 | 行数 | 说明 |
|---|---|---|
play/index.html |
95 | 玩法中心首页 |
assets/app.css |
176 | 玩法/工具统一公共样式（所有静态页引用根目录这份） |
assets/app.js |
217 | 公共小工具（下载、读文件、toast、localStorage、统计埋点、回到顶部、暗色/i18n 注入） |
play/piano/index.html |
405 | 电脑钢琴（自包含，不用公共样式） |
play/drum-machine/index.html |
384 | 鼓机，Web Audio 实时合成 |
play/pixel-art/index.html |
334 | 像素画板，导出 PNG |
play/algo-visual/index.html |
389 | 五个排序/查找算法 |
play/retro-games/index.html |
899 | 贪吃蛇（AI 对战 / 4 档难度 / 20·30·40 地图）+ 2048 + 打砖块 |
play/gomoku/index.html |
461 | 五子棋 AI（棋型评分 + Minimax，三档难度） |
play/tetris/index.html |
464 | 俄罗斯方块（7-bag、墙踢、消行、等级加速） |
play/lucky-wheel/index.html |
366 | 抽奖转盘（canvas + rAF 缓动，不重复模式） |
play/clockwork-city/* |
~3000 | 发条巨城：自研 Canvas 伪 3D 蒸汽机械射击，拆成 index.html + theme.css + engine/world/input/quest/audio/ui/main.js 七个文件，普通 <script> 按依赖顺序加载，无构建工具；真射线命中与爆头、机瞄与后坐力、4 张大地图轮换、8 把枪、3 档难度、六边形雷达、报纸结算、主线首章 + 3 支线、jhp-cc-save v3 本地存档（兼容 v2） |
tools/index.html |
95 | 工具中心首页 |
tools/dev-tools/index.html |
480 | 八合一工具箱（含纯 JS 的 MD5） |
tools/typing-test/index.html |
318 | 打字测速 |
tools/qr-code/index.html |
229 | 二维码生成器 |
tools/qr-code/assets/qrcode.js |
— | 二维码库（第三方，MIT） |
tools/pomodoro/index.html |
390 | 番茄钟 + 白噪音 |
tools/calc/index.html |
201 | 科学计算器（键盘 + 历史 + 白名单安全求值） |
tools/diff/index.html |
137 | 文本差异对比（LCS 逐行 diff） |
tools/world-clock/index.html |
212 | 世界时钟（Intl 时区 + 表盘 + 时差换算） |
tools/password/index.html |
199 | 密码生成器（crypto 随机 + 熵值强度） |
play/ 和 tools/ 都是纯静态 HTML，不需要 PHP，删掉任何一个子目录其它照常工作。
lib/site.php 里的关键函数
base_url() // 返回 '../' 之类，让子目录页面也能找到 assets/
build_tree($dir) // 递归扫描 docs/，生成目录树
doc_title($file) // 读文档第一行 # 标题
safe_doc_path($rel) // 路径校验，防目录穿越
count_words($text) // 字数统计（中文按字，英文按词）
reading_minutes($w) // 阅读时长 = 字数 / 400
extract_toc(&$html) // 提取 h2/h3 生成右侧目录，并加锚点
search_docs($q) // 全文搜索
render_sidebar($tree) // 渲染左侧多级侧边栏
render_admin_tree() // 渲染后台文档树
page_header/footer() // 页面头尾（含搜索框、顶部导航）
base_url()是为了让admin/这类子目录里的页面也能正确引用assets/style.css， 之前后台页面样式失效就是这个原因，现在已经修好了。
想改东西，改哪里
| 想改 | 改哪个文件 |
|---|---|
| 站名 | config.php 的 $site_name |
| 首页标语 | index.php 的 .hero-sub |
| 配色（文档站） | assets/style.css 顶部 :root 变量 |
| 配色（玩法/工具） | 根 assets/app.css 顶部 :root 变量（静态页统一用这一份） |
| 阅读速度（字/分钟） | config.php 的 $words_per_minute |
| 顶部导航 | lib/site.php 的 page_header() |
| 玩法中心有哪些卡片 | play/index.html 的 .card-grid |
| 工具中心有哪些卡片 | tools/index.html 的 .card-grid |
| 暗色模式配色 | assets/style.css 末尾的 [data-theme="dark"] 块（改暗色变量） |
| 后台密码 | config.php 的 $admin_password_hash |
安全设计
- 路径穿越防护：
safe_doc_path()逐段拒绝..，../../config.php这种请求会被挡掉 - 密码哈希：用
password_hash（bcrypt）存，不存明文 - 会话校验：所有写操作（
admin/save.php）要求登录 session - Markdown 安全模式：
Parsedown::setSafeMode(true)，屏蔽原始 HTML 注入 - 玩法/工具不碰服务器：全部是纯前端页面，不往服务器发任何数据
性能
- 开了 GZIP 压缩
- 每次访问实时渲染，文档量小（几十篇）时毫秒级
- 玩法/工具页面是静态 HTML，服务器直接吐文件，最省资源
- 整站（不含 deploy 目录）大约 435 KB，主机给的 128MB 空间绰绰有余
已知限制
- 没有多用户 / 权限系统
- 没有版本历史（改了就是改了，建议重要文档自己备份）
- 没有内置评论
- 图片需要自己管理（空间只有 128MB）
- 搜索只搜 .md 文档，搜不到玩法/工具页面（所以每个玩法都配了一篇说明文档）