mirror of
https://github.com/XiaoDaiGua-Ray/ray-template.git
synced 2026-11-17 16:13:36 +08:00
30 lines
37 KiB
HTML
30 lines
37 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN" dir="ltr">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
<title>发行版本与快速启动 · Ray Template 文档</title>
|
||
<meta name="description" content="Ray Template 6.0.1 的 Monorepo 架构、版本分界、组件与交互示例。">
|
||
<meta name="generator" content="VitePress v1.6.4">
|
||
<link rel="preload stylesheet" href="/ray-template/docs/assets/style.6J0m3LtX.css" as="style">
|
||
<link rel="preload stylesheet" href="/ray-template/docs/vp-icons.css" as="style">
|
||
|
||
<script type="module" src="/ray-template/docs/assets/app.DZGstFSm.js"></script>
|
||
<link rel="preload" href="/ray-template/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
|
||
<link rel="modulepreload" href="/ray-template/docs/assets/chunks/theme.DuEXda0y.js">
|
||
<link rel="modulepreload" href="/ray-template/docs/assets/chunks/framework.D8G7yXPy.js">
|
||
<link rel="modulepreload" href="/ray-template/docs/assets/guide_distributions.md.CquuxHZi.lean.js">
|
||
<link rel="icon" type="image/svg+xml" href="/ray-template/docs/ray-mark.svg">
|
||
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
|
||
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
|
||
</head>
|
||
<body>
|
||
<div id="app"><div class="Layout" data-v-f9c03b6e><!--[--><!--]--><!--[--><span tabindex="-1" data-v-770676c7></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-770676c7>跳转到正文</a><!--]--><!----><header class="VPNav" data-v-f9c03b6e data-v-b2a7789c><div class="VPNavBar" data-v-b2a7789c data-v-d231c45b><div class="wrapper" data-v-d231c45b><div class="container" data-v-d231c45b><div class="title" data-v-d231c45b><div class="VPNavBarTitle has-sidebar" data-v-d231c45b data-v-49754884><a class="title" href="/ray-template/docs/" data-v-49754884><!--[--><!--]--><!--[--><img class="VPImage logo" src="/ray-template/docs/ray-mark.svg" alt data-v-a9cdc337><!--]--><span data-v-49754884>Ray Template</span><!--[--><!--]--></a></div></div><div class="content" data-v-d231c45b><div class="content-body" data-v-d231c45b><!--[--><!--]--><div class="VPNavBarSearch search" data-v-d231c45b><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="搜索文档"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">搜索文档</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-d231c45b data-v-49bcf2ef><span id="main-nav-aria-label" class="visually-hidden" data-v-49bcf2ef> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink active" href="/ray-template/docs/guide/start.html" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>指南</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/ray-template/docs/guide/architecture.html" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>架构</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/ray-template/docs/migration.html" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>版本分界</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/ray-template/docs/reference/" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>API 参考</span><!--]--></a><!--]--><!--[--><a class="VPLink link vp-external-link-icon VPNavBarMenuLink" href="https://xiaodaigua-ray.github.io/ray-template/" target="_blank" rel="noreferrer" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>Ray Admin</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-d231c45b data-v-a4a103b4><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-a4a103b4 data-v-2b76c23f data-v-54e91c08><span class="check" data-v-54e91c08><span class="icon" data-v-54e91c08><!--[--><span class="vpi-sun sun" data-v-2b76c23f></span><span class="vpi-moon moon" data-v-2b76c23f></span><!--]--></span></span></button></div><div class="VPSocialLinks VPNavBarSocialLinks social-links" data-v-d231c45b data-v-584f2254 data-v-91f5f172><!--[--><a class="VPSocialLink no-icon" href="https://github.com/XiaoDaiGua-Ray/ray-template" aria-label="github" target="_blank" rel="noopener" data-v-91f5f172 data-v-976d6037><span class="vpi-social-github"></span></a><!--]--></div><div class="VPFlyout VPNavBarExtra extra" data-v-d231c45b data-v-766dd493 data-v-57202eaf><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-57202eaf><span class="vpi-more-horizontal icon" data-v-57202eaf></span></button><div class="menu" data-v-57202eaf><div class="VPMenu" data-v-57202eaf data-v-80746065><!----><!--[--><!--[--><!----><div class="group" data-v-766dd493><div class="item appearance" data-v-766dd493><p class="label" data-v-766dd493>主题</p><div class="appearance-action" data-v-766dd493><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-766dd493 data-v-2b76c23f data-v-54e91c08><span class="check" data-v-54e91c08><span class="icon" data-v-54e91c08><!--[--><span class="vpi-sun sun" data-v-2b76c23f></span><span class="vpi-moon moon" data-v-2b76c23f></span><!--]--></span></span></button></div></div></div><div class="group" data-v-766dd493><div class="item social-links" data-v-766dd493><div class="VPSocialLinks social-links-list" data-v-766dd493 data-v-91f5f172><!--[--><a class="VPSocialLink no-icon" href="https://github.com/XiaoDaiGua-Ray/ray-template" aria-label="github" target="_blank" rel="noopener" data-v-91f5f172 data-v-976d6037><span class="vpi-social-github"></span></a><!--]--></div></div></div><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-d231c45b data-v-0ee194e1><span class="container" data-v-0ee194e1><span class="top" data-v-0ee194e1></span><span class="middle" data-v-0ee194e1></span><span class="bottom" data-v-0ee194e1></span></span></button></div></div></div></div><div class="divider" data-v-d231c45b><div class="divider-line" data-v-d231c45b></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-f9c03b6e data-v-60478e07><div class="container" data-v-60478e07><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-60478e07><span class="vpi-align-left menu-icon" data-v-60478e07></span><span class="menu-text" data-v-60478e07>文档目录</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-60478e07 data-v-debc629b><button data-v-debc629b>回到顶部</button><!----></div></div></div><aside class="VPSidebar" data-v-f9c03b6e data-v-efe03c19><div class="curtain" data-v-efe03c19></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-efe03c19><span class="visually-hidden" id="sidebar-aria-label" data-v-efe03c19> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-90a0702d><section class="VPSidebarItem level-0 has-active" data-v-90a0702d data-v-d34e54b2><div class="item" role="button" tabindex="0" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><h2 class="text" data-v-d34e54b2>入门</h2><!----></div><div class="items" data-v-d34e54b2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/start.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>快速开始</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/distributions.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>发行版本与快速启动</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/architecture.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>v6 Monorepo 架构</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/migration.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>v5 与 v6 的版本分界</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/first-page.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>第一个业务页面</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-90a0702d><section class="VPSidebarItem level-0" data-v-90a0702d data-v-d34e54b2><div class="item" role="button" tabindex="0" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><h2 class="text" data-v-d34e54b2>开发指南</h2><!----></div><div class="items" data-v-d34e54b2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/routing.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>路由、菜单与权限</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/layout.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>应用布局与状态</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/requests.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>接口、取消与 Mock</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/backend.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>服务端接入与标准契约</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/appearance.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>主题与国际化</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/tooling.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>工程检查与部署</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-90a0702d><section class="VPSidebarItem level-0" data-v-90a0702d data-v-d34e54b2><!----><div class="items" data-v-d34e54b2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/reference/" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>API 参考</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-f9c03b6e data-v-7ec33352><div class="VPDoc has-sidebar has-aside" data-v-7ec33352 data-v-b0483432><!--[--><!--]--><div class="container" data-v-b0483432><div class="aside" data-v-b0483432><div class="aside-curtain" data-v-b0483432></div><div class="aside-container" data-v-b0483432><div class="aside-content" data-v-b0483432><div class="VPDocAside" data-v-b0483432 data-v-6d31e1a2><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-6d31e1a2 data-v-a849a091><div class="content" data-v-a849a091><div class="outline-marker" data-v-a849a091></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-a849a091>本页目录</div><ul class="VPDocOutlineItem root" data-v-a849a091 data-v-78a615b5><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-6d31e1a2></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-b0483432><div class="content-container" data-v-b0483432><!--[--><!--[--><!--[--><div class="ray-doc-meta"><span>开发指南</span><a href="/ray-template/docs/reference/source.html">版本 <code>6.0.1</code></a></div><!--]--><!--]--><!--]--><main class="main" data-v-b0483432><div style="position:relative;" class="vp-doc _ray-template_docs_guide_distributions" data-v-b0483432><div><h1 id="发行版本与快速启动" tabindex="-1">发行版本与快速启动 <a class="header-anchor" href="#发行版本与快速启动" aria-label="Permalink to "发行版本与快速启动""></a></h1><p>同一套前端通过源码导出提供独立使用方式。Admin、文档和公共包之间保留明确依赖边界,Mock 与自有后端遵循同一套 API 契约。源码归档包含可编辑的工程文件,需要安装依赖并构建后运行。</p><h2 id="纯前端发行包" tabindex="-1">纯前端发行包 <a class="header-anchor" href="#纯前端发行包" aria-label="Permalink to "纯前端发行包""></a></h2><p>在仓库根目录执行:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dist:frontend</span></span></code></pre></div><p>输出目录为 <code>dist/distributions/</code>,包含 <code>ray-template-frontend-<version>/</code> 和同名 <code>.tar.gz</code>。解压后进入源码目录,使用仓库指定的 Node.js 26.13.0 与 pnpm 12.16.1:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --frozen-lockfile</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span></code></pre></div><p>默认打开 <code>/ray-template/</code>,通过 MSW 体验登录、用户管理、路由和其他示例。纯前端包保留 Admin、文档、10 个共享包及必要工具;不包含后端工作区、数据库驱动、Redis 客户端、服务端启动脚本或数据库配置。前端开发、构建和文档使用不需要 Docker。</p><p>接入自己的服务时配置 <code>VITE_API_BASE_URL</code>、<code>VITE_API_MOCK=false</code>,具体协议见<a href="./backend.html">服务端接入</a>。这些前端变量会进入浏览器产物,只能放公开配置。</p><h2 id="发行物追溯" tabindex="-1">发行物追溯 <a class="header-anchor" href="#发行物追溯" aria-label="Permalink to "发行物追溯""></a></h2><p>归档内的 <code>distribution.json</code> 记录:</p><ul><li>发行类型和版本。</li><li>来源 Git 提交及是否含未提交改动;没有 Git 信息时保留已知的来源信息。</li><li>实际包含的 workspace 清单和源码文件数量。</li><li>导出内容的 SHA-256 摘要。</li></ul><p>导出会按依赖图保留所需工作区、裁剪锁文件、移除不可用命令与专属说明,并排除 <code>.git</code>、<code>node_modules</code>、本地环境配置、凭据、构建结果和临时验证资料。<code>pnpm dist:check</code> 检查导出计划和依赖完整性;干净环境中的安装、构建、运行需要另行验证。</p><p>导出命令只生成本地源码目录和归档。</p><h2 id="全栈发行包" tabindex="-1">全栈发行包 <a class="header-anchor" href="#全栈发行包" aria-label="Permalink to "全栈发行包""></a></h2><p>在完整仓库运行:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dist:fullstack</span></span></code></pre></div><p>同一目录会生成 <code>ray-template-fullstack-<version>/</code> 与同名 <code>.tar.gz</code>。它包含相同的前端源码以及 <code>apps/server</code>、数据库迁移、Redis 配置和启动工具。后端采用 NestJS 12.3.3、Prisma 7.10.1、PostgreSQL 18,Redis 客户端为 6.3.1;Compose 配置使用 Redis 8.2.11。具体锁定版本以发行包清单和锁文件为准。</p><h3 id="本地开发" tabindex="-1">本地开发 <a class="header-anchor" href="#本地开发" aria-label="Permalink to "本地开发""></a></h3><p>安装依赖并准备 Docker Compose,然后运行:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fullstack:setup</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev:full</span></span></code></pre></div><p><code>setup</code> 首次创建 <code>apps/server/.env.local</code>,生成数据库、Redis、管理员随机密码和 JWT 签名密钥,启动 PostgreSQL 与 Redis,执行迁移并初始化管理员。配置文件按私有文件创建;请在本机读取初始用户名和密码,勿提交、上传或放进前端变量。Mock 的 <code>123456</code> 只用于前端演示。</p><p>再次执行 <code>setup</code> 会复用配置、保留已有账号和数据库内容。<code>dev:full</code> 等待后端就绪后再启动前端,通过 Vite 将同源 <code>/api/</code> 请求代理给后端,并关闭 Mock。默认地址为 <code>http://127.0.0.1:9527/ray-template/</code>;可用 <code>ADMIN_DEV_PORT</code> 和 <code>PORT</code> 分别指定前端和后端端口。按 <code>Ctrl+C</code> 关闭开发进程;<code>pnpm fullstack:stop</code> 停止 Compose 服务并保留数据卷。</p><h3 id="使用已有数据库与-redis" tabindex="-1">使用已有数据库与 Redis <a class="header-anchor" href="#使用已有数据库与-redis" aria-label="Permalink to "使用已有数据库与 Redis""></a></h3><p>将 <code>DATABASE_URL</code> 和 <code>REDIS_URL</code> 放入当前进程的安全环境中,然后执行:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fullstack:setup</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --external</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev:full</span></span></code></pre></div><p><code>--external</code> 跳过 Docker 服务启动,仍执行迁移和初始化。已有 <code>apps/server/.env.local</code> 时保留该文件,进程环境优先。应使用为本项目准备的数据库;迁移和初始化会创建或更新本项目的数据结构。停止外部数据服务由其部署环境负责。</p><h3 id="创建真实登录账号" tabindex="-1">创建真实登录账号 <a class="header-anchor" href="#创建真实登录账号" aria-label="Permalink to "创建真实登录账号""></a></h3><p>在用户管理新增资料后,有 <code>users:credentials</code> 权限的管理员可以为该账号点击 <strong>设置密码</strong>。已登录用户可在头像菜单的 <strong>个人信息</strong> 页面修改自己的密码,需要输入当前密码。改密或重设会撤销该账号的所有会话。密码要求 12–128 个字符。</p><p>无法登录时,运维可通过安全环境提供 <code>CREDENTIAL_USERNAME</code> 与 <code>CREDENTIAL_PASSWORD</code>,再执行 <code>pnpm server:credential:set</code>。该命令适用于直接访问项目数据库的运维终端。重复执行 <code>setup</code> 不会创建改名前的账号,也不会重置密码。不要把密码写进命令行、终端记录或 AI 对话。</p><h3 id="服务与运行检查" tabindex="-1">服务与运行检查 <a class="header-anchor" href="#服务与运行检查" aria-label="Permalink to "服务与运行检查""></a></h3><table tabindex="0"><thead><tr><th>命令或接口</th><th>用途</th></tr></thead><tbody><tr><td><code>pnpm server:build</code></td><td>生成 Prisma Client 并构建独立服务端产物</td></tr><tr><td><code>pnpm server:start</code></td><td>从服务端构建产物启动</td></tr><tr><td><code>pnpm server:check</code></td><td>服务端类型、单元/平台测试和构建</td></tr><tr><td><code>pnpm server:test:integration</code></td><td>使用 <code>TEST_DATABASE_URL</code>、<code>TEST_REDIS_URL</code> 验证真实存储与 HTTP 行为</td></tr><tr><td><code>GET /api/health/live</code></td><td>进程存活检查</td></tr><tr><td><code>GET /api/health/ready</code></td><td>PostgreSQL 与 Redis 就绪检查</td></tr></tbody></table><p>全栈包含配置校验、接口授权、会话撤销、Redis 限流、安全响应头、CORS、请求 ID、脱敏日志和操作审计。Redis 不可用时管理接口返回 503,不切换到每进程的临时认证或限流数据。缓存只用于可重建的演示读取结果,权限和会话每次从数据库核验。</p><p>生产模式默认关闭演示接口,并从后端提供的运行菜单中移除演示页面。路由编辑器仍可维护完整配置。真实后端请求失败不会回退到 Mock。</p><h3 id="容器启动" tabindex="-1">容器启动 <a class="header-anchor" href="#容器启动" aria-label="Permalink to "容器启动""></a></h3><p>准备仓库指定的 Node.js 26.13.0,以及已启动的 Docker 和 Compose v2 插件(<code>docker compose version</code>、<code>docker info</code> 均应成功)。从解压后的全栈源码或完整仓库根目录运行:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">node</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> scripts/fullstack.mjs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> up</span></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 使用 pnpm 时,也可以运行 pnpm fullstack:up</span></span></code></pre></div><p>此命令创建私有配置、构建 Admin 和 API、启动 PostgreSQL 与 Redis、执行迁移和初始化,等服务就绪后打印本机入口。宿主机无需预先安装前端依赖。默认入口为 <code>http://127.0.0.1:8080/ray-template/</code>,可通过 <code>APP_PORT</code> 改端口。使用 <code>node scripts/fullstack.mjs stop</code> 停止服务,数据卷保留。多个隔离实例要为每份配置指定不同的 <code>RAY_COMPOSE_PROJECT</code>、宿主机端口和 <code>APP_PROXY_NETWORK</code>。</p><p>Nginx 将同源 <code>/api/</code> 转发给后端。默认只在回环地址暴露宿主机端口,生产模式关闭演示(可用 <code>APP_DEMO_ENABLED=true</code> 显式开启)。外部 HTTPS 入口设置 <code>APP_ORIGINS</code> 为实际浏览器来源、<code>APP_SESSION_COOKIE_SECURE=true</code>,保留同源的 <code>/ray-template/</code> 和 <code>/api/</code>。示例 Nginx 会覆盖转发头;如再接外层反代,应在 Nginx 的 real IP 设置中只信任实际上一跳,并验证转发头无法伪造限流地址。代理网段冲突时,修改 <code>APP_PROXY_NETWORK</code>(例如 <code>172.30.68</code>)。容器连接外部数据库或 Redis 时,用正确编码的 <code>APP_DATABASE_URL</code>、<code>APP_REDIS_URL</code> 指定目标;已有服务的本机开发走 <code>setup --external</code>。</p><h3 id="给部署者和-ai-的验收清单" tabindex="-1">给部署者和 AI 的验收清单 <a class="header-anchor" href="#给部署者和-ai-的验收清单" aria-label="Permalink to "给部署者和 AI 的验收清单""></a></h3><ol><li>先确认发行物含 <code>apps/server</code>、<code>deploy/compose.yaml</code> 和 <code>scripts/fullstack.mjs</code>。默认选容器方式;需要热更新时走本地开发;已有 PostgreSQL、Redis 时用专用数据库和 Redis 前缀。端口占用就换 <code>APP_PORT</code>(容器)或 <code>PORT</code>、<code>ADMIN_DEV_PORT</code>(本机开发);数据库和 Redis 映射分别用 <code>POSTGRES_PORT</code>、<code>REDIS_PORT</code>。</li><li>准备 PostgreSQL 迁移权限、Redis 连接以及服务端私有配置。部署副本共享同一个 <code>JWT_SECRET</code>(32 个随机字节的 base64url 编码),不同环境使用不同密钥。升级旧工作区可重跑 <code>setup</code> 或 <code>up</code> 补齐缺少的密钥;先备份 PostgreSQL,再应用迁移,旧令牌需重新登录。初始化配置中的密码只用于第一次建号。</li><li>验证 <code>GET /api/health/live</code>、<code>GET /api/health/ready</code> 均返回 200,匿名 <code>GET /api/admin/route-config</code> 返回 401。登录后检查用户管理、个人信息和路由管理;为测试账号设置密码,并确认只读账号不能调用写接口。空菜单账号仍应能打开个人信息。</li><li>如只有存活检查通过,用 Compose 的 <code>ps -a</code>、<code>logs initialize server</code> 检查迁移、初始化与连接。命令需使用 <code>--env-file apps/server/.env.local -f deploy/compose.yaml --profile app -p <项目名></code>。只看脱敏日志,不回显环境文件。若浏览器登录后仍返回 401,检查实际访问源、同源代理和 Cookie 的 Secure 设置。对外部署还要验证目标环境的 HTTPS、备份恢复与代理限流。</li></ol><p><code>node deploy/smoke.mjs</code> 使用独立的临时 Compose 项目检查迁移、构建、登录、路由、CORS、演示开关和代理限流,并只清理它创建的测试资源。</p><h3 id="生成分支与-release-资产" tabindex="-1">生成分支与 Release 资产 <a class="header-anchor" href="#生成分支与-release-资产" aria-label="Permalink to "生成分支与 Release 资产""></a></h3><p>维护者在 GitHub Actions 从 <code>main</code> 手动运行 <strong>Source distributions</strong>。默认只验证并上传本次运行的归档。要更新生成的 <code>frontend</code> 分支,选择 <code>sync_frontend</code>;该分支从主线导出,不用于独立开发。要给已有 Release 附加两个源码包及 SHA-256 校验文件,另行填写 <code>release_tag</code>。工作流检查标签版本及提交、验证归档,并保留已上传的同名资产。</p></div></div></main><footer class="VPDocFooter" data-v-b0483432 data-v-028296d9><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-028296d9><span class="visually-hidden" id="doc-footer-aria-label" data-v-028296d9>Pager</span><div class="pager" data-v-028296d9><a class="VPLink link pager-link prev" href="/ray-template/docs/guide/start.html" data-v-028296d9><!--[--><span class="desc" data-v-028296d9>上一页</span><span class="title" data-v-028296d9>快速开始</span><!--]--></a></div><div class="pager" data-v-028296d9><a class="VPLink link pager-link next" href="/ray-template/docs/guide/architecture.html" data-v-028296d9><!--[--><span class="desc" data-v-028296d9>下一页</span><span class="title" data-v-028296d9>v6 Monorepo 架构</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-f9c03b6e data-v-20a32aa3><div class="container" data-v-20a32aa3><!----><p class="copyright" data-v-20a32aa3>© 2022–至今 Ray · MIT License</p></div></footer><!--[--><!--]--></div></div>
|
||
<script>window.__VP_HASH_MAP__=JSON.parse("{\"guide_appearance.md\":\"CbhgFuQy\",\"guide_architecture.md\":\"C5f_dStb\",\"guide_backend.md\":\"DpcumSyL\",\"guide_distributions.md\":\"CquuxHZi\",\"guide_first-page.md\":\"DHqwAt4V\",\"guide_layout.md\":\"DahQh0oB\",\"guide_requests.md\":\"CZYqS1G0\",\"guide_routing.md\":\"CGQ9b6Or\",\"guide_start.md\":\"Dyl7ULXt\",\"guide_tooling.md\":\"B1a_atZw\",\"index.md\":\"B3Ji-_c4\",\"migration.md\":\"YnSE1eTb\",\"playground_shell.md\":\"jNpqmXOa\",\"reference_components.md\":\"Bj8x64hc\",\"reference_components_app.md\":\"C7wJGrLN\",\"reference_components_barcode.md\":\"05kFYpfB\",\"reference_components_chart.md\":\"CmF0yQj-\",\"reference_components_collapse-grid.md\":\"ef3DmpmT\",\"reference_components_draggable-card.md\":\"DDSUCtdc\",\"reference_components_flow.md\":\"3NC8SRXL\",\"reference_components_form.md\":\"Cm6Gckyr\",\"reference_components_iframe.md\":\"DMWNIbE9\",\"reference_components_modal.md\":\"ti54dHz0\",\"reference_components_more-dropdown.md\":\"X2TUbUVU\",\"reference_components_qr-code.md\":\"UBtVbqXa\",\"reference_components_route-transition.md\":\"DiLEQcKJ\",\"reference_components_segment.md\":\"BNEEW09r\",\"reference_configuration.md\":\"ZPlSg6sS\",\"reference_directives.md\":\"CpZHS1Mm\",\"reference_hooks.md\":\"B7r2QBiR\",\"reference_hooks_appearance.md\":\"CHWjp8Rw\",\"reference_hooks_browser.md\":\"BF1b28Me\",\"reference_hooks_interaction.md\":\"9MI9QLxG\",\"reference_hooks_layout.md\":\"ZBgUvajf\",\"reference_hooks_navigation.md\":\"UCy1Te6m\",\"reference_hooks_output.md\":\"9qljHfmL\",\"reference_icons.md\":\"DXUtpdoz\",\"reference_index.md\":\"B02Licr3\",\"reference_source.md\":\"BoVc3275\",\"reference_store.md\":\"BWJxztnK\",\"reference_store_navigation.md\":\"DGO1GZ0U\",\"reference_store_runtime.md\":\"BHW5rI8i\",\"reference_store_setting.md\":\"CF5XUyTp\",\"reference_store_signing.md\":\"DLMf-30Z\",\"reference_table-pro-examples.md\":\"Bw8WoLY8\",\"reference_table-pro.md\":\"D91H49U1\",\"reference_utils.md\":\"CFovP9sb\",\"reference_utils_browser.md\":\"WqdwCNPp\",\"reference_utils_core.md\":\"BRV-numN\",\"reference_utils_storage.md\":\"DZTFQ860\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"zh-CN\",\"dir\":\"ltr\",\"title\":\"Ray Template\",\"titleTemplate\":\":title · Ray Template 文档\",\"description\":\"Ray Template 6.0.1 的 Monorepo 架构、版本分界、组件与交互示例。\",\"base\":\"/ray-template/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"src\":\"/ray-mark.svg\",\"alt\":\"\"},\"siteTitle\":\"Ray Template\",\"nav\":[{\"text\":\"指南\",\"link\":\"/guide/start\",\"activeMatch\":\"^/guide/\"},{\"text\":\"架构\",\"link\":\"/guide/architecture\"},{\"text\":\"版本分界\",\"link\":\"/migration\"},{\"text\":\"API 参考\",\"link\":\"/reference/\",\"activeMatch\":\"^/reference/\"},{\"text\":\"Ray Admin\",\"link\":\"https://xiaodaigua-ray.github.io/ray-template/\"}],\"sidebar\":{\"/reference/\":[{\"text\":\"API 参考总览\",\"link\":\"/reference/\"},{\"text\":\"组件\",\"link\":\"/reference/components\",\"collapsed\":true,\"items\":[{\"text\":\"TablePro\",\"link\":\"/reference/table-pro\"},{\"text\":\"TablePro 在线示例\",\"link\":\"/reference/table-pro-examples\"},{\"text\":\"RForm 与 useForm\",\"link\":\"/reference/components/form\"},{\"text\":\"RModal\",\"link\":\"/reference/components/modal\"},{\"text\":\"RChart 与 useChart\",\"link\":\"/reference/components/chart\"},{\"text\":\"RFlow 与 useFlow\",\"link\":\"/reference/components/flow\"},{\"text\":\"RCollapseGrid\",\"link\":\"/reference/components/collapse-grid\"},{\"text\":\"RSegment\",\"link\":\"/reference/components/segment\"},{\"text\":\"RMoreDropdown\",\"link\":\"/reference/components/more-dropdown\"},{\"text\":\"RIframe\",\"link\":\"/reference/components/iframe\"},{\"text\":\"RBarcode\",\"link\":\"/reference/components/barcode\"},{\"text\":\"RDraggableCard\",\"link\":\"/reference/components/draggable-card\"},{\"text\":\"RTransitionComponent\",\"link\":\"/reference/components/route-transition\"},{\"text\":\"RIcon 与 SVG 图标\",\"link\":\"/reference/icons\"},{\"text\":\"二维码\",\"link\":\"/reference/components/qr-code\"},{\"text\":\"应用组件与 Provider\",\"link\":\"/reference/components/app\"}]},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\",\"collapsed\":true,\"items\":[{\"text\":\"导航与菜单\",\"link\":\"/reference/hooks/navigation\"},{\"text\":\"布局与滚动\",\"link\":\"/reference/hooks/layout\"},{\"text\":\"主题、语言和水印\",\"link\":\"/reference/hooks/appearance\"},{\"text\":\"分页与右键菜单\",\"link\":\"/reference/hooks/interaction\"},{\"text\":\"窗口、全屏和日期\",\"link\":\"/reference/hooks/browser\"},{\"text\":\"DOM 截图与打印\",\"link\":\"/reference/hooks/output\"}]},{\"text\":\"指令\",\"link\":\"/reference/directives\"},{\"text\":\"Store\",\"link\":\"/reference/store\",\"collapsed\":true,\"items\":[{\"text\":\"Setting\",\"link\":\"/reference/store/setting\"},{\"text\":\"Menu 与 KeepAlive\",\"link\":\"/reference/store/navigation\"},{\"text\":\"Runtime 与 Lock Screen\",\"link\":\"/reference/store/runtime\"},{\"text\":\"Signing\",\"link\":\"/reference/store/signing\"}]},{\"text\":\"工具函数\",\"link\":\"/reference/utils\",\"collapsed\":true,\"items\":[{\"text\":\"基础、日期和数值\",\"link\":\"/reference/utils/core\"},{\"text\":\"缓存与兼容加密\",\"link\":\"/reference/utils/storage\"},{\"text\":\"Vue 与浏览器工具\",\"link\":\"/reference/utils/browser\"}]},{\"text\":\"应用配置\",\"link\":\"/reference/configuration\"},{\"text\":\"文档与源码版本\",\"link\":\"/reference/source\"}],\"/\":[{\"text\":\"入门\",\"items\":[{\"text\":\"快速开始\",\"link\":\"/guide/start\"},{\"text\":\"发行版本与快速启动\",\"link\":\"/guide/distributions\"},{\"text\":\"v6 Monorepo 架构\",\"link\":\"/guide/architecture\"},{\"text\":\"v5 与 v6 的版本分界\",\"link\":\"/migration\"},{\"text\":\"第一个业务页面\",\"link\":\"/guide/first-page\"}]},{\"text\":\"开发指南\",\"items\":[{\"text\":\"路由、菜单与权限\",\"link\":\"/guide/routing\"},{\"text\":\"应用布局与状态\",\"link\":\"/guide/layout\"},{\"text\":\"接口、取消与 Mock\",\"link\":\"/guide/requests\"},{\"text\":\"服务端接入与标准契约\",\"link\":\"/guide/backend\"},{\"text\":\"主题与国际化\",\"link\":\"/guide/appearance\"},{\"text\":\"工程检查与部署\",\"link\":\"/guide/tooling\"}]},{\"text\":\"API 参考\",\"link\":\"/reference/\"}]},\"outline\":{\"label\":\"本页目录\",\"level\":[2,3]},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"搜索文档\",\"buttonAriaLabel\":\"搜索文档\"},\"modal\":{\"noResultsText\":\"未找到相关内容\",\"resetButtonTitle\":\"清除搜索\",\"footer\":{\"selectText\":\"打开\",\"navigateText\":\"切换\",\"closeText\":\"关闭\"}}}}},\"skipToContentLabel\":\"跳转到正文\",\"docFooter\":{\"prev\":\"上一页\",\"next\":\"下一页\"},\"returnToTopLabel\":\"回到顶部\",\"sidebarMenuLabel\":\"文档目录\",\"darkModeSwitchLabel\":\"主题\",\"lightModeSwitchTitle\":\"切换到浅色\",\"darkModeSwitchTitle\":\"切换到深色\",\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/XiaoDaiGua-Ray/ray-template\"}],\"footer\":{\"copyright\":\"© 2022–至今 Ray · MIT License\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
|
||
|
||
</body>
|
||
</html> |