功能介绍

Mahesvara 的能力按模块划分如下。除特别标注外，均为 0.22.x 当前线上版本已具备并经过生产验证的能力。

核心 Web 服务

多站点 vhost：配置文件以 sites.<host> 声明站点，进程内按 Host 路由（含 * 通配兜底），一个进程托管多个独立站点
静态托管：目录即站点，自动识别 Content-Type；index.html 目录索引
deny 静态防护：目录与扩展名双黑名单，.env .key .db .git backup 等敏感资源一律 403；目录按目录段精确匹配，只拦目录本身、不误伤带该子串的文件名（v0.11.1）
SPA fallback：history 路由前端应用回退到 index.html
HTTP → HTTPS 301：80 端口统一跳转，未知 Host 返回 404
静态缓存头：HTML 不缓存（no-cache），css/js/图片/字体 public, max-age=3600
大文件流式：超过 1MB 的文件走 C 层 64KB 分块流式发送，支持 Range 断点续传（v0.9.1；v0.11.1 补齐 vhost 公共管道 {"file": …} 分支，多站点全链路生效）

TLS 与传输

TLS-SNI 多证书：cert_dir/<host>.crt 与 .key 存在即自动装载对应站点，互不干扰
证书热加载：每 60 秒轮询证书文件内容哈希，变化即覆盖 SNI 槽——零重启、零断连换证；配合 acme.sh 等自动续期工具即可实现"续期 → 60 秒内自动生效"的闭环
自动 SSL（v0.9.9）：加载 vhost 发现站点无证书 → 后台自动 ma-cert issue（ACME http-01 签发 + 自动安装 cert_dir），失败按 10min~24h 退避、auto_cert: false 可关——新站开箱即得 HTTPS
SNI 证书槽预检（v0.22.1）：运行时 SNI 槽是定长数组，超一格的表现不是"新站不通"而是 register_tls 报错 → 进程退出 → 整机 443 全挂。--check 与启动横幅同屏打印 SNI 证书槽 N/256 槽已用，≥80% 告警、超容量直接判错拒绝上线；容量可由 env MA_SNI_SLOT_CAP 覆盖
HTTP/3（QUIC）：config 开启后 UDP 随主服务同端口启动，Alt-Svc 自动通告
per-site 限流：rate_limit: {per_ip, window_sec} 即启用，每 IP 滑动窗口超限返回 429（nginx limit_req 思想，默认关闭）

md 多语言站点

Mahesvara 特有的站点模式（v0.5 起），本站即此模式运行：

Markdown 即内容：src/*.md（front-matter：title/description/order/lang/prompt）经模板自动构建为静态 HTML；默认语言裸路径，其它语言独立 /en/… URL
多语言可收录：每个语言独立静态 URL → 内容恒定，CDN 随意缓存、无 cloaking 风险；自动生成 hreflang、canonical、sitemap 与 robots
LLM 翻译在 md 层：翻译对象是纯文本 Markdown（不碰 HTML 与代码围栏），diff 可审、人能校对
磁盘缓存控成本：缓存键 sha256(源 + provider + model) + lang，重启即命中；源文件变化只重翻该页；顺序翻译不并发烧钱
预热 + 热更：启动后台自动构建，源文件变更 60 秒内自动重建
安全兜底：构建未就绪返回 503，绝不回源泄漏 src/cache/templates/i18n（默认 deny）
public/ 静态资源直读：站点根下 public/ 里的 css/js/图片按 URL 直接映射读取（/css/style.css → public/css/style.css），改了样式文件立刻生效，不必等 md 重建（v0.22.5 修正该分支的判定条件）

.px 脚本路由（v0.21 起）

把「某些 URL 交给 PuXian 脚本」做成配置项，不再为一个功能开一个端口：

四种匹配：{"exact": "/api/x"}、{"prefix": "/api/"}、{"regex": "^/u/[0-9]+$"}、{"dir": "/ticket"}（目录自动映射：/ticket/login → ticket/login.px）
URL 里不出现 .px：写作接近 PHP，但不需要 PHP-FPM、不需要反代跳数，就是同进程内 os_capture 派生执行
方法白名单：路径命中但方法不符 → 405 + Allow（不是 404）
入参：CGI/1.1 子集 —— REQUEST_METHOD / REQUEST_URI / QUERY_STRING / PATH_INFO / REMOTE_ADDR / HTTP_* 走环境变量，请求体走 stdin（>1 MiB 落盘通路）
出参：stdout 前若干 Name: value + 空行 + 正文，支持 Status: 4xx …；Content-Length / Transfer-Encoding / Connection 由 Ma 决定（脚本写了也忽略，防响应走私）
安全：脚本必须落在 px_root 内（拒 .. 与非 .px）、配了 px_routes 的站点自动把 .px 并入 deny_exts（源码不可被下载）、timeout_ms 超时杀进程组、max_conc 超限返回 503、fallthrough 控制"同名 .px 不存在时是否回落静态"
编译缓存（v0.22）：mode:"auto" 先走解释轨采样，连续几次超阈值 → 后台 px build → 之后直接 exec 编译产物（实测 28~36 ms → 10~18 ms；重计算脚本 216 ms → 13 ms）；缓存 key = 脚本子树全部 .px 内容哈希 + px 版本，改脚本自动失效；--px-probe 只编译不执行，--px-cache-clear 清缓存
编译失败的硬判定（v0.22.4）：px build 对"import 的模块找不到"只打警告、返回 0，旧版本因此把必然报错的产物缓存成"编译成功"，每个请求都先失败再回落解释轨（实测稳定 1.1 秒/次）。现在编译前静态预检跨目录 import、输出含"找不到模块"直接判失败、缓存 key 换代淘汰坏产物、失败冷却 60 秒

站点级跳转与重定向（v0.20 / v0.22.2）

redirect_to_host：同一份内容挂在多个 Host 上时做 301 归一（GET/HEAD → 301，其余方法 → 308 保留方法与体，避开 nginx 把 POST 降级成 GET 的旧坑）；自指向不跳，防配置写成死循环
redirects：站点级精确路径重定向 {"from": "/login.html", "to": "https://id.example.com/login.html"}，from 精确匹配、to 可绝对地址或站内路径，缺省 302，其余方法自动升 307/308，查询串原样带走
位次固定：防护链（请求体上限 / 限流 / deny）先跑，跳转在其后、缓存与业务之前；/healthz 与 /__metrics 的早退更早，监控不受影响

反向代理

prefix 路由：proxy_routes 声明 prefix → target，命中即反代到上游（keep-alive 连接池）
失败语义明确：上游不可达/中断稳定返回 502，不崩溃、不拖垮进程（v0.8）
请求头透传：Host / X-Forwarded-For / X-Forwarded-Proto 与常见请求头（UA / Accept / Accept-Language / Origin / Referer 等）透传上游（v0.9.3、v0.9.8）
响应头白名单透传：仅透传受控响应头（Content-Type 等），防 CRLF 注入

进程内 HTTP 缓存（ma-cache）

进程内缓存（v0.10）：站点 cache 段启用；只缓存可安全缓存的响应——GET/HEAD、2xx/3xx、无 Set-Cookie、Cache-Control 允许；TTL 夹逼 min_ttl ≤ ttl ≤ max_ttl（默认 60/300/300 秒）；SQLite 元数据 + 磁盘对象文件 + LRU 上限；命中 / 回源 / 淘汰指标进 /__metrics
提前刷新（SWR 变体，v0.11）：TTL 消耗至 prefetch_pct（默认 90%，如 TTL=300 → 270 秒）后，命中请求立即返回当前内容并后台异步回源续期——用户零回源等待、窗口内几乎不 miss；inflight 单飞（30 秒）防并发回源、失败按 prefetch_backoff_sec（默认 10 秒）退避防源站风暴；prefetch_pct=0 可关（回到纯过期 miss）
宁回源不错缓存：Expires 头保守不解析（视为无缓存头）；bypass 前缀路径永不缓存

可观测与安全

访问日志：ts ip host method path status ms，记录来源 IP（IPv6 原样）
/__metrics：只读 JSON 指标，进程级 totals + 各 host 计数（v0.11 起含 cache 命中/回源/刷新计数）；自身请求不计入日志
/healthz：健康检查 {"ok": true, "uptime": ms}
ma-telemetry CLI：access.log + /__metrics 聚合入 SQLite，输出性能报告（总览/分位/host/状态码/IP/慢请求）+ 阈值告警 + 数据清理
ma-audit CLI：安全审计——窗口内按 IP 威胁判定（404 洪峰、敏感路径探测、403 试探、5xx 异常源），输出威胁清单、法证时间线与 firewall-cmd 封禁建议（dry-run，高危由外层确认）

运维与可靠性

配置 lint：--check / -t（nginx -t 语义），坏配置拒绝启动与 reload
SIGHUP 优雅 reload：对应 systemctl reload mahesvara——重读配置 + 校验后热应用，坏配置拒绝应用、旧配置照跑；不可热生效项（监听端口/HTTP3/LLM 通道）告警提示 restart
重启竞态根治：v0.8 起修复端口/状态竞态，Restart 场景下不打架
进程内自愈：md worker 周期性崩溃自动防御（v0.9.2），上游异常不拖垮进程
证书闭环：证书文件变更 → 60 秒内自动换证，全程零重启零断连

工程与安全设计

PuXian 语言实现：以自举编译器 pxc 构建，产出静态二进制、零动态依赖，部署即拷即用
LLM key 零落盘：环境变量注入 / AES-256-GCM 加密 key 文件 / 直连文殊词元缓存网关（ws_token_cache，unix socket，key 不落盘、统一缓存计费）
模块化源码：main（入口）/ cfg（配置）/ http（HTTP 层）/ px_route（.px 脚本路由与编译缓存）/ cache + cache_store（进程内 HTTP 缓存）/ md_render（渲染）/ template（模板注入）/ llm（LLM 通道）/ translate（翻译编排）/ md_site（md 站点构建）
外围 CLI 拆族：ma-md / ma-site / ma-cert / ma-diag / ma-telemetry / ma-audit / ma-sec（单机守护）/ ma-alertd（告警上报）独立小工具，各司其职，全部静态二进制
生态清晰：语言本体（PuXian）、软件本体（Mahesvara）、内容站点（wsai_chat 等）为独立仓库，边界明确

想了解版本演进脉络，见里程碑；回到首页。