nova-admin

多站点复用的通用后台底座（Laravel 12 + Filament 5）：广告管理、站点设置、静态页面、ads.txt、robots.txt、后台中文、账号密码登录、默认管理员、后台 Logo 跳前台。

composer create-project laravel/laravel:^12.0 mysite
cd mysite

composer require inova/nova-admin

已依赖 Filament 5，无需单独安装。

默认 SQLite；用 MySQL 等先配 .env。 生产 APP_URL 须为完整 URL（如 https://example.com）——robots.txt 的 Sitemap 行按它生成。

php artisan nova-admin:install

一条命令搞定全部：接入 admin Panel、跑迁移、建默认管理员、初始化 robots/站点设置、 填充示例广告、发布静态资源、建 storage 软链。无需手动碰 AdminPanelProvider.php。

附带处理：公开文件（robots.txt/ads.txt/vendor/livewire）加入 .gitignore， App\Models\User 自动接入 FilamentUser + HasNovaAdminAccess（仅 users.is_admin 为真的用户可进后台， 默认管理员已标记；User 已有 canAccessPanel 的不动），并生成差异版 config/nova-admin.php。

php artisan serve

访问 http://127.0.0.1:8000/admin → 用 nova / nova 登录。

上线前立即在后台改默认密码。

广告位分两类：

• 布局级位（ad_layout_positions，默认 anchor / interstitial，外加 global_head）：浮层 / 脚本类， 位置与页面结构无关，布局里放一次聚合组件即可。包新增此类位后，项目升级、后台填码就能展示，不用改模板。
• 内容位（其余位，如 banner）：放在页面哪里由各站点决定，模板里手动成对放置。

{{-- layouts/app.blade.php --}}
<head>
    @stack('ad-head')   {{-- 页面内容位的 head，必须在下面组件之前 --}}
    <x-ad-layout-head :enabled="($section ?? null)?->ads_enabled ?? true" />  {{-- global_head 固定最后 --}}
</head>
<body>
    @yield('content')
    <x-ad-layout-body :enabled="($section ?? null)?->ads_enabled ?? true" />  {{-- 不套居中容器 --}}
</body>

{{-- 页面模板里的内容位：head 与 body 必须成对，无生效广告时不产生 DOM --}}
@push('ad-head')
    <x-ad-head position="home_banner1" />
@endpush
<x-ad-body position="home_banner1" />

enabled=false 时只输出 global_head（统计、站点验证这类站点级脚本任何页面都要加载）。 ad_disabled_views 里的视图（默认 pages.show、errors::404）会被注入 $section->ads_enabled = false。 nova-admin:doctor 扫描模板：内容位只放了一半、动态 :position、引用未启用的位直接失败； 内容位完全没放默认警告，--strict 时失败。项目测试里断言 nova-admin:doctor 退出码为 0 即可守住模板契约。

前台只读页面挂 nova.public 中间件组（不启会话、无 Cookie、带 Cache-Control，可进 CDN 边缘缓存）， 缓存时长见 nova-admin.page_cache。包同时全局下发 HSTS（仅 HTTPS 请求，nova-admin.security.hsts 可关）。

// bootstrap/app.php
->withRouting(
    web: __DIR__.'/../routes/web.php',
    then: fn () => Route::middleware('nova.public')->group(base_path('routes/public.php')),
)

static_pages.footer_views 里的视图（默认 layouts.app）会拿到 $footerPages：已启用的静态页，按 presets 顺序排列。

边缘副本最长留到当天结束。后台改了广告位、站点设置、静态页、ads.txt / robots.txt， 包会在请求 / 命令 / 队列任务结束时自动清本站（APP_URL 的 host）缓存，同一次操作多次写入只清一次。

项目自己的批量改动必须自己调，包感知不到：切换领域、清空或删除内容、切换主题、采集入库之后：

purge_edge_cache('domain_switched');            // 当前请求 / 命令 / 队列任务结束时清
purge_edge_cache('domain_switched', now: true); // 立即清，返回是否成功

不清的后果：旧首页链着已删除的内容，访客点进去是 404，而 404 本身也会被边缘缓存。

需要 .env 里的 CLOUDFLARE_API_TOKEN（由 webdeploy 部署时写入；本包是公开仓库，不内置 token）； zone 按域名自动查（只有 token 没有 Zone.Read 权限时才需要配 CLOUDFLARE_ZONE_ID）。local / testing 环境不清。

布局 <head> 里放 <x-nova-seo />，按后台「站点设置」输出 <title>（按 meta_title_template 拼装， 支持 {title}、{site_name}、%s）、description、keywords、canonical、favicon、OG / Twitter 卡片。 页面用 @section('title', 'About') 只写自身标题；description、keywords、canonical、robots、og_type、og_image 同理可用 section 或同名属性覆盖（属性写 og-type、image）。robots 有值才输出；og_type 默认 website； keywords 未覆盖时取站点设置。 未写 title 的页面（通常是首页）取「站点名 - 副标题」。

site_setting('copyright');        // 站点设置值，未保存过时回退 nova-admin.site_defaults
site_media_url('logo_path');      // 上传的 Logo / Favicon 的 URL，未设置返回 null

site_config('site_name');        // 读站点配置

// Facade
use Inova\NovaAdmin\Facades\SiteConfig;
SiteConfig::get('site_name', 'default');
SiteConfig::set('site_name', 'My Site');         // string
SiteConfig::set('ads_enabled', true, 'boolean'); // 按 type 存取

后台「静态页面」管理关于、隐私政策、服务条款等富文本落地页。安装时按 nova-admin.static_pages.presets 预置一批页面（含 AdSense 法务五件套 + Cookie Policy）， static_pages 表是唯一数据源——不要在项目里另建 pages 表镜像它，两套数据必然漂移。

约定：正文首个 <h1> 即页面标题（保存时自动提取为 title 并在 body_html 中剥离）， Meta Description 留空时自动取正文摘要。前台模板契约三件套：

包默认注册 GET /{slug}（仅限 presets 内的 slug，不劫持其他 URL），路由名 pages.show， 默认用包内简洁模板渲染，激活页面自动进 sitemap。后台保存，前台立即生效。

有自己视觉的项目只换视图，路由和数据流不动：

// config/nova-admin.php
'static_pages' => [
    'frontend' => [
        'view'       => 'pages.show',   // 换成你的 Blade，收 $page 变量
        'route_name' => 'pages.show',
    ],
],

多主题项目视图名需动态解析（如 theme_view('page')）时，关闭包路由自己写， 但数据仍读 static_page()，不要建自己的表：

// routes/web.php（NOVA_STATIC_FRONTEND=false 关闭包路由）
Route::get('/{slug}', function (string $slug) {
    abort_unless($page = static_page($slug), 404);

    return view(theme_view('page'), compact('page'));
})->whereIn('slug', array_keys(config('nova-admin.static_pages.presets')))->name('pages.show');

零散场景仍可用 helper 按 slug 读取（仅返回已启用页面，未找到或停用返回 null）：

@php($page = static_page('privacy-policy'))

@if ($page)
    <h1>{{ $page->title }}</h1>
    <div class="prose">{!! $page->body_html !!}</div>
@endif

body_html 为富文本 HTML，输出用 {!! !!}（内容由后台管理员录入，可信）。

包自带 GET /sitemap.xml（robots.txt 默认模板已指向它）。静态条目在 config nova-admin.sitemap.urls 配置；动态内容在项目 AppServiceProvider::boot 注册：

use Inova\NovaAdmin\Facades\Sitemap;

Sitemap::register(fn () => Article::published()->get()->map(fn ($a) => [
    'loc'      => route('articles.show', $a),
    'lastmod'  => $a->updated_at,          // 可选，DateTime 或字符串
    'priority' => '0.7',                   // 可选；changefreq 同理
]));

输出带缓存（sitemap.cache_ttl，默认 1800 秒），内容更新后可执行 php artisan nova-admin:clear-sitemap-cache 立即刷新；项目自带 sitemap 时置 sitemap.enabled = false 关闭包路由。

php artisan nova-admin:install                  # 接入 Panel、建表并初始化
php artisan nova-admin:create-admin [--force]   # 创建/重置默认管理员
php artisan ad:seed [--off]                     # 填充测试广告（先清空）/ 禁用广告
php artisan nova-admin:clear-sitemap-cache       # 清 sitemap 缓存
php artisan ads:import-site-ad-config <file>    # 导入 webdeploy 下发的站点广告配置
php artisan nova-admin:doctor [--strict]        # 自检广告位与协议映射、模板渲染点
php artisan nova-admin:purge-edge-cache         # 立即清本站 Cloudflare 边缘缓存

webdeploy 把 GAM 广告位代码与 ads.txt 打成一个 JSON 下发到站点，本命令负责落库：

{
  "meta": { "protocol": 1 },
  "slots": {
    "global_head":   { "name": "Global", "head_code": "<script>…loader + enableServices…</script>" },
    "home_banner_1": { "name": "Home 1", "head_code": "…", "body_code": "…" }
  },
  "ads_txt": "google.com, pub-…, DIRECT, f08c47fec0942fa0"
}

• slots → ad_spots（按 position 覆盖式写入并置为启用），ads_txt → 与后台「Ads.txt」页同一条存储路径（DB + public/ads.txt）。 静态文件走「临时文件 + rename」原子替换，写到一半失败不会留下截断的 ads.txt；写文件失败仍会落库，由 /ads.txt 路由兜底动态输出。
• 两个部件各自独立成败：未下发的部件不出现在回包里；下发了却写不进去的部件必须回 failed，不会静默略过。
• slots 内部是一个事务：任一广告位结构非法、协议键未知、或映射目标未在 ad_positions 启用，整批回滚。
• slots 必须包含 global_head（承载 loader 与 enableServices）。
• 结果通过 stdout 的 marker 回传，这是 webdeploy 唯一认可的边界：

__SITE_AD_CONFIG_RESULT_BEGIN__{"slots":{"status":"success","written_positions":[…]},"ads_txt":{"status":"success"}}__SITE_AD_CONFIG_RESULT_END__

任一部件 failed 时命令退出码为 1。协议键与本包 position 的对应关系在 config('nova-admin.ads_protocol.position_map')：协议键带下划线（home_banner_1）， 本包 position 不带（home_banner1）。站点确实不用某个位时，在 ad_positions 与 position_map 里都写成 false；但保留不用的位没有代价，去掉反而会让平台勾到它时整体导入失败。

GPT 要求 slot 定义早于 enableServices，即 global_head 放最后——布局组件已保证这一点， 页面的 @stack('ad-head') 写在 <x-ad-layout-head /> 之前即可。

nova-admin:install 生成差异版 config/nova-admin.php：宿主只写与包默认不同的部分， 升级包后新增的广告位、协议映射等自动继承。合并规则：

• 关联数组逐键合并：写一行就覆盖 / 追加一项；
• 列表（如 sitemap.urls、favicon.accepted_types）整体替换；
• 空数组等于没写；
• 写 false 删除包内的键（如 'interstitial' => false）；包里本身是布尔值的键，false 就是普通的关闭。

完整配置项见包内 config/nova-admin.php（vendor:publish --tag=nova-admin-config 可导出查看）。常用项：

'panel'        => ['id' => 'admin'],
'ad_positions' => [ /* 自定义广告位枚举 */ ],
'ads_protocol' => ['version' => 1, 'position_map' => [ /* 协议键 => position */ ]],
'ad_layout_positions' => ['anchor' => true, 'interstitial' => true],  // 布局级位
'ad_disabled_views'   => ['pages.show', 'errors::404'],             // 不投广告的视图
'page_cache'   => ['ttl' => 3600, 'cdn_ttl' => 86400],
'cloudflare'   => ['api_token' => env('CLOUDFLARE_API_TOKEN'), 'zone_id' => env('CLOUDFLARE_ZONE_ID')],
'security'     => ['hsts' => true],
'navigation'   => [
    'groups' => ['settings' => '基础设置', 'content' => '内容管理', 'system' => '系统'],
    'sort' => 90,
],
'admin'        => ['default_name' => 'nova', 'login_field' => 'name'],
'admin_brand'  => ['logo_link_to_front' => true, 'front_url' => '/', 'new_tab' => true],
'ads_txt'      => ['enabled' => true, 'empty_behavior' => 'delete'],
'site_settings' => [   // 站点设置页的上传限制，max_size 单位 KB，0 = 不限
    'favicon' => ['accepted_types' => ['image/x-icon', 'image/png'], 'max_size' => 1024],
    'logo'    => ['max_size' => 2048],
],
'robots_txt'   => ['enabled' => true, 'sitemap_url' => null],
'static_pages' => [
    'enabled' => true,
    'presets' => [ /* slug => [英文, 中文]，安装时预置；置 enabled=false 关闭整个功能 */ ],
],

• 加纯业务功能（如 Game / Destination）：项目正常写 Filament Resource/Page，与本包并列注册，互不干扰。
• 给包的表加字段：项目写补充 ALTER 迁移加列，在项目自己的 Resource/Service 中使用扩展后的模型。
• 简单业务配置：直接走 site_configs 键值（SiteConfig::set），无需建表。
• 定制包页面视图：发布 vendor:publish --tag=nova-admin-views 后修改 Blade。

首次安装用 composer install，升级用 composer update inova/nova-admin，其余相同：

php artisan nova-admin:install --force
php artisan optimize:clear && php artisan optimize

nova-admin:install 会自动处理 FilamentUser / HasNovaAdminAccess 接入（避免后台 403）、发布 Filament / Livewire 静态资源、storage:link 与公开文件忽略。

生产服务器需确保 storage/、public/vendor/livewire 归属 web 用户。若启用了 opcache.validate_timestamps=0，发布后 reload php-fpm。