部署说明

本文档说明银行核心知识库站点和 apps/ 应用层的本地构建、自动发布和日报定时任务。

1、本地构建

Web 站点构建：

cd web
npm install
npm run check
npm run build

Apps 门户和子应用构建：

cd apps
npm run build

构建产物目录：

web/.vitepress/dist/
apps/dist/

2、本地预览

Web 开发预览：

cd web
npm run dev

Apps 静态构建预览：

cd apps
npm run build

3、当前正式发布策略

当前正式环境已采用 GitHub Actions + Docker + GitOps 自动发布：

推送到 main
-> GitHub Actions 构建 web/
-> GitHub Actions 构建 apps/
-> Docker 镜像推送到 ECR
-> 更新 GitOps 镜像 tag
-> 集群拉起新版本
-> https://wiki.onetic.cc/ 对内可访问

站点路径约定：

• /：主 Wiki
• /apps/：应用导航页
• /apps/gh-daily/：GitHub 日报

对应 workflow：

• .github/workflows/ci.yml：主站和 apps/ 共用的正式发布流程
• .github/workflows/gh-daily.yml：日报定时生成，并复用正式发布流程

4、日常更新流程

更新 wiki/、project-docs/ 或 apps/
-> 本地验证
-> push 到 main
-> GitHub Actions 自动发布

说明：

• wiki/ 是业务知识源目录。
• project-docs/ 是项目规范和说明源目录。
• web/wiki/ 和 web/project-docs/ 是同步生成目录，不直接手工维护。
• apps/ 是独立静态应用层，正式发布时会一起并入站点根目录下的 /apps/。
• apps/.env 是本地共享配置；CI 中对应使用仓库级 Secrets / Variables。
• npm run check 会先同步内容，再检查本地 Markdown 链接和图片引用。
• npm run build 会先同步内容，再生成静态站点。

5、gh-daily 自动化

gh-daily 额外有一个定时任务：

每天北京时间 00:20
-> 生成前一天 GitHub 日报
-> 输出 apps/gh-daily/data/YYYY-MM-DD.json
-> 自动提交回 main
-> 复用站点发布流程上线

建议统一配置这些仓库级参数：

• Secrets：APPS_GH_TOKEN、APPS_AI_API_KEY
• Variables：APPS_GH_ORG、APPS_AI_ENDPOINT、APPS_AI_MODEL、APPS_TIMEZONE

如果主分支策略不允许默认 GITHUB_TOKEN 直接推送，再补一个：

• Secret：CORE_BANK_PUSH_TOKEN

6、历史手动部署参考

当前正式环境已切到自动发布，这一节保留为手动落地静态文件时的参考。

构建完成后，只部署静态产物目录中的内容，不上传整个项目源码。

本地打包示例：

cd web
npm run check
npm run build
cd .vitepress/dist
tar -czf core-bank-wiki.tar.gz .

如果需要把 apps/ 一起手动带上，则将 apps/dist/ 同步到站点根目录下的 apps/ 子目录。

7、Nginx 部署示例

把静态产物上传到服务器，例如：

/var/www/core-bank-wiki/

Nginx 可参考：

server {
    listen 80;
    server_name example.com;

    root /var/www/core-bank-wiki;
    index index.html;

    location / {
        try_files $uri $uri/ $uri.html =404;
    }
}

如果后续部署在子路径，例如 /core-bank/，需要同步调整 VitePress base 配置，并确保 apps/ 的链接策略一起调整。

8、验收检查

部署后至少检查：

• 首页可以打开。
• https://wiki.onetic.cc/apps/ 可以打开。
• https://wiki.onetic.cc/apps/gh-daily/ 可以打开最新日报。
• 左侧侧边栏可以展开并跳转。
• 搜索可以使用。
• 截图页面图片可以显示。
• Mermaid 图可以渲染。
• Mermaid 图可以点击放大。
• 刷新深层页面不报 404。