website-docs/ 包含官网、文档、共享样式和全部构建部署脚本，可独立复制和构建，不依赖仓库外层文件。官网和文档共用一个域名、一次构建和一份部署产物。
产品、部署、API 和开发文档统一在这里维护。旧 docs/ 的有效内容已按主题合并，过时和重复正文已删除；迁移取舍及仍保留的工程资源见迁移记录；该记录仅供维护者使用，不发布到站点。
/：产品首页。/docs/：直接进入“快速上手”。/docs/…：完整文档，保留分类导航、搜索和侧栏。
站点只占用这两个路径：根目录下只有 index.html、404.html 和 docs/。官网的脚本、样式和图片都放在 /docs/_home/ 下，所以上游网关只需转发 /（精确匹配）和 /docs/ 前缀。build 会拒绝引用这两个路径以外资源的页面。
顶栏高 64px、横向铺满。两边使用 README 原版商标，共用颜色、字体和深浅色偏好；Logo 在当前标签返回官网。官网和文档各自使用适合当前页面的导航。
使用 Node.js 24，在仓库的 website-docs/ 目录执行。首次构建或依赖锁文件变更后，先安装依赖：
cd website-docs
npm run setup
npm run build
npm run package:sitebuild 会编译官网、检查文档链接和 Mermaid、编译文档，并校验合并后的资源路径。全部通过后更新 static-site/；package:site 将其打包到 releases/。
只需把压缩包上传到服务器。服务器不需要 Node.js，也不需要 WeKnora 后端或独立文档服务。
每次发布使用一个新的空目录，避免混入旧站点文件。下面的 20260915-1 是示例发布编号，后续发布换一个编号：
sudo mkdir -p /srv/www/weknora/releases/20260915-1
sudo tar -xzf weknora-site-v0.8.2.tar.gz -C /srv/www/weknora/releases/20260915-1解压后该目录下应直接有 index.html、404.html、docs/，无需再套一层 static-site/。
以 deploy/nginx.conf 为模板添加站点配置，修改：
server_name 你的域名;
root /srv/www/weknora/releases/20260915-1;如果域名已有 HTTPS 配置，保留原来的证书及监听设置，把模板中的 root、index 和 location 规则合入现有站点配置。域名应指向这台服务器。
必须保留文档的 .html 路由解析规则；不要把所有未知路径回退到官网 index.html。当前构建部署在域名根路径，不支持直接放进 /weknora/ 等子目录。
检查配置后重载：
sudo nginx -t
sudo nginx -s reload访问以下路径：
/：官网。/docs/：快速上手。/docs/03-features/23-memory：长期记忆文档，直接打开和刷新均正常。/docs/not-found：返回 404。
再确认搜索、深浅色切换和 Logo 返回官网正常。
后续更新重复构建、打包、上传到新目录，再修改 Nginx root 并重载。需要回滚时，将 root 改回上一发布目录。确认新版本稳定后再清理旧发布目录。
从干净源码即可构建，无需在宿主机安装 Node.js 或提前生成静态文件。Dockerfile 使用两个阶段：Node.js 24 按两份锁文件安装依赖并构建官网与文档，最终 Nginx 镜像只包含静态产物和服务配置。
在仓库根目录执行：
docker build -t weknora-site:0.8.2 website-docs
docker run -d --name weknora-site --restart unless-stopped -p 8080:80 weknora-site:0.8.2访问 http://服务器地址:8080/。如使用域名和 HTTPS，让现有反向代理转发到该端口即可。镜像内已经包含官网、文档和 Nginx 路由配置。
容器内的 Nginx 默认监听 80 端口，可以用环境变量 WEBSITE_NGINX_PORT 修改，无需重新构建。使用 --network host，或者部署平台要求容器监听指定端口时，这样设置：
docker run -d --name weknora-site --restart unless-stopped -e WEBSITE_NGINX_PORT=8080 -p 8080:8080 weknora-site:0.8.2只是想换一个对外端口时，改 -p 左侧的宿主机端口就够了，例如 -p 9000:80。
也可以只复制 website-docs/ 目录，在该目录执行 docker build -t weknora-site:0.8.2 .。构建上下文必须是 website-docs/，宿主机的依赖、旧构建产物和部署包由 .dockerignore 排除。
从旧文档镜像迁移时，将容器端口映射或反向代理目标端口从 8081 改为 80（宿主机端口可自行选择，例如 -p 8081:80）。域名根路径 / 现在提供官网，/docs/ 提供文档，反向代理需覆盖整个站点并保留请求路径。容器使用 Nginx 官方镜像的默认入口，无需额外的 docker-entrypoint.sh。
构建后可在安装了 Node.js 24 和 Docker 的机器上执行以下检查，无需安装 npm 依赖。检查会临时启动容器并自动清理，验证两站路由、静态资源、404、压缩和响应头：
cd website-docs
npm run test:docker -- weknora-site:0.8.2使用 Node.js 24 LTS（目录内提供 .nvmrc，使用 nvm 时可执行 nvm use）。首次获取源码后安装依赖（分别按文档和官网的锁文件安装）：
cd website-docs
npm run setup
npm run build
npm run preview预览地址：http://127.0.0.1:3000/。修改源码后重新构建并刷新；可用 npm run preview -- --port 8080 指定其他端口。
npm run check
npm run test:integration集成检查需要安装 Google Chrome，验证主题同步、两边导航、搜索、手机端控件及直达文档路由。可用 SITE_TEST_URL 指定待验证的站点。
开发时可分别使用 npm run dev:homepage（官网）和 npm run dev:docs（文档）获得热更新；完整站内跳转请使用统一构建后的 npm run preview。
npm run build:docs 只编译文档，npm run build:homepage 只编译官网；正式发布使用 npm run build，输出会同时包含两者。VERSION 是这份站点构建使用的发布版本。
homepage/：Next.js 官网源码、品牌素材及独立依赖锁文件。01-getting-started/至06-development/：文档正文，原有路径不变。.vitepress/：文档站配置与主题。public/、sample-data/：文档截图和示例。shared/：品牌变量、顶栏样式及共用图标。scripts/：统一构建、检查、预览和打包。static-site/：唯一的部署目录，由构建生成。deploy/、Dockerfile：Nginx 和 Docker 部署配置。releases/：生成的部署压缩包。
品牌素材来源见 homepage/BRAND-ASSETS.md。产品视频使用 README 中的 GitHub 原始附件，播放需要访问 GitHub；页面、文档和截图随包部署。