Skip to content
RJiazhenPublic

About

Nuxt Content blog template inspired by HugoRCD/canvas.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

canvas-ai

基于 Nuxt + Nuxt Content + Nuxt UI 的个人站点模板,可选接入本地 / 云端 AI Agent(FastAPI + LangChain,向量检索基于 pgvector)。

线上示例:https://rjiazhen.top/


快速开始(无 AI 功能)

Fork 本仓库到自己的账号,再克隆到本地。

开发环境

  • Node.js:24.16.0
  • pnpm:11.13.1

安装依赖

在仓库根目录执行:

pnpm install

启动项目

若使用 VS Code / Cursor,且已安装 Chrome,可直接用 Run and Debug 中的 Web: Nuxt 启动。

或在根目录执行:

pnpm dev

启动完成后访问 http://localhost:3000。

因为 AI Agent 服务未配置,所以会隐藏 AI 对话按钮和相关功能。


完整本地开发(含 AI)

建议在上线前先在本地把「Postgres + AI Agent + 站点」跑通。

补充开发工具

在「快速开始」所需环境之外,再安装:

准备 AI Agent 环境变量

运行以下命令,复制 .env.example 为 .env.local:

cp apps/ai-agent/.env.example apps/ai-agent/.env.local

.env.local 不会提交到 Git。字段说明见 apps/ai-agent/.env.example。

配置大模型

选择一家同时提供 LLM 与向量(Embedding)模型、且兼容 OpenAI API 的供应商:注册账号 → 创建 API Key → 拿到兼容模式的 Base URL。

仓库默认指向阿里云百炼(DashScope)兼容模式:

变量 含义 默认示例
OPENAI_API_KEY API Key(必填) (空,需自行填写)
OPENAI_API_BASE OpenAI 兼容 Base URL https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL 对话模型 qwen3.7-max
EMBEDDING_MODEL 向量模型 qwen3.7-text-embedding
EMBEDDING_DIMENSION 向量维度(须与模型一致) 768

若换用其他供应商,请一并修改上述变量,并保证 EMBEDDING_DIMENSION 与所选 Embedding 模型输出维度一致。

若保持上述默认模型配置不变,请到阿里云百炼控制台确认对应模型是否仍有免费额度(或已开通计费),避免额度不足导致调用失败。

启动本地 AI Agent

若使用 VS Code / Cursor,可以直接使用 Run and Debug 中的 AI Agent: debug (uv) 启动(会自动启动本地的 Postgres 服务和 AI Agent 服务)。

或在根目录执行以下命令:

pnpm dev:ai-agent:postgres   # Docker Compose 启动 pgvector Postgres(5432)
pnpm dev:ai-agent            # 启动 AI Agent(默认 8080)

说明:

  • 首次启动会拉取镜像 pgvector/pgvector:pg18-trixie(需能访问 Docker Hub)。
  • 数据库会占用 5432 端口,注意避免端口冲突。
  • 根脚本已通过 uv run 执行,一般不必再手动写 uv 前置命令;若 .venv 尚未创建,uv run / uv sync 会按需安装。

打开 http://localhost:8080/docs,能看到接口文档即表示 Agent 启动成功。

启动带 AI 的网页应用

确定 AI Agent 服务已启动后,在根目录执行以下命令启动网页应用:

pnpm dev

访问 http://localhost:3000,页面右下角应出现 AI 悬浮入口。

注意:如果通过 .env.development 配置了 NUXT_AI_AGENT_API_BASE_URL,需要将其改回 http://localhost:8080,否则无法正常访问本地的 AI Agent 服务。


生产部署

将数据库换为线上实例,再分别部署 Agent 与站点,即可对外提供完整能力。个人博客体量下,Neon / Google Cloud Run / Cloudflare Workers 的免费额度通常够用。

准备工作

正式部署前建议先具备:

  1. 访问 Google Cloud、Cloudflare 等平台的网络条件;
  2. 一张 Visa / Master 等外币信用卡(注册 Google Cloud 账号时可能需要绑定)。

数据库(以 Neon 为例)

Neon 免费账号大致提供:每个项目 0.5 GB 存储、每月 5 GB 网络传输、每月每项目 100 CU-hours,一般足够个人博客使用。

  1. 在 Neon 注册并创建项目(需支持 pgvector)。

  2. 在控制台执行一次:

    CREATE EXTENSION IF NOT EXISTS vector;
  3. 复制连接串(形如 postgresql://user:pass@host/db?sslmode=require)。本仓库的 DB_DSN 不要带 postgresql:// 前缀——应用会自行补上。例如 Neon 给出:

    postgresql://user:pass@ep-xxx.aws.neon.tech/neondb?sslmode=require
    

    则写入 apps/ai-agent/.env.local(本地验证)或后续 Cloud Run 环境变量:

    DB_DSN=user:pass@ep-xxx.aws.neon.tech/neondb?sslmode=require
  4. 本地再跑 pnpm dev:ai-agent,打开 http://localhost:8080/docs,确认能连上线上库;在该页面调用 /api/chat 做对话测试,并确认数据库中新增了记录。

更多连接说明见 Neon:Connect Neon。

部署 Agent 服务(Google Cloud Run)

本模板的 Agent 需部署到 Google Cloud Run;站点访问远程 Agent 时也依赖 Cloud Run 的身份验证(见下文服务账号 JSON)。按请求计费时,免费额度大致包括:每月 200 万次请求、180,000 vCPU-seconds、360,000 GiB-seconds、2,500 build-minutes,以及结算账号合计 0.5 GB 镜像存储(建议配置清理政策,见下文)。

Google Cloud 准备

  1. 打开 Google Cloud,完成账号注册;
  2. 新增一个项目,后续在该项目下创建 Cloud Run 服务。

新增 Google Cloud Run 服务

  1. 打开 Google Cloud Run 控制台,选择「部署 Web 服务」中的「连接代码库」;
  2. 在「设置 Developer Connect」中选择 fork 的仓库(可能需要 GitHub 授权),「构建类型」的「Dockerfile」填写 /apps/ai-agent/Dockerfile;
  3. 填写「服务名称」;
  4. 「地区」选择「asia-east1 (台湾)」(该地区价格相对较低);
  5. 「身份验证」选择「需要进行身份验证」,并勾选「Identity and Access Management (IAM)」;
  6. 在「容器、网络、安全性」→「容器」→「变量和密钥」中添加以下环境变量(推荐先在 Secret Manager 添加密钥,再以密钥形式引用):
    1. DB_DSN:上文从 Neon 连接串提取出的值(不含 postgresql:// 前缀);
    2. OPENAI_API_KEY:大模型 API Key;
    3. (可选)OPENAI_API_BASE:OpenAI 兼容 Base URL,默认 https://dashscope.aliyuncs.com/compatible-mode/v1;
    4. (可选)LLM_MODEL:对话模型,默认 qwen3.7-max;
    5. (可选)EMBEDDING_MODEL:向量模型,默认 qwen3.7-text-embedding;
    6. (可选)EMBEDDING_DIMENSION:向量维度(须与模型一致),默认 768。
  7. 确认并创建服务。

之后可按所选供应商与账号剩余的免费额度,调整上述可选模型相关变量。

修改触发器

等待服务启动完成后,还需修改触发器配置。因为 AI Agent 位于本仓库子目录,若不限制路径,修改其他文件也会触发重新部署。

  1. 在刚部署好的服务详情页面,点击「修改仓库设置」进入触发器修改页面;
  2. 在「来源」→「与分支 main 匹配」→「包含的文件过滤条件 (glob)」中填入 apps/ai-agent/**。

本地测试(可选)

部署完成后,因服务启用了身份验证,可在本机安装 Google Cloud CLI,登录同一 Google 账号,将线上服务代理到本地做冒烟测试(把服务名与区域换成你的值):

gcloud run services proxy <service> --region=<region>
# 例如:gcloud run services proxy personal-website-ai-agent --region=asia-east1

然后访问 http://localhost:8080/docs,或:

curl http://localhost:8080/health
curl -sI http://localhost:8080/openapi.json

修改 Artifact Registry 配置

Cloud Run 构建的镜像会保存在 Artifact Registry。按 官方定价,存储 Always Free 额度为每个结算账号每月 0.5 GiB(该账号下所有项目合计);超出后按量计费。建议预先配置清理政策,避免旧镜像堆满免费额度:

  1. 打开 Artifact Registry,勾选对应仓库,点击「修改代码库」;
  2. 在「清理政策」中选择「删除多个软件制品」;
  3. 点击「添加清理政策」,添加以下两条:
    1. 名称:delete-old;政策类型:「按条件删除」;
    2. 名称:keep-recent-5;政策类型:「保留最新版本」,保留数量:5;
  4. 点击底部「更新」,保存修改。

生成身份验证 JSON 文件

上一步创建 AI Agent 时选择了「需要进行身份验证」,因此外部调用时必须完成身份验证。

按以下步骤生成密钥文件:

  1. 打开 Google Cloud IAM 服务账号管理页面;
  2. 选择部署了服务的项目;
  3. 创建或选择一个服务账号,点击其电子邮件进入账号详情页;
  4. 为该服务账号授予目标 Cloud Run 服务的 Cloud Run Invoker(roles/run.invoker)权限;
  5. 在「密钥」→「添加键」中选择「创建新密钥」(JSON),下载密钥文件,供下一步写入 Cloudflare 环境变量 NUXT_GOOGLE_SERVICE_ACCOUNT_JSON。

部署网页应用(以 Cloudflare Workers 为例)

Cloudflare Workers 免费计划大致提供:每天 100,000 次请求、每月 3,000 分钟构建时间,一般足够个人博客使用。

  1. 在 Cloudflare 创建 Workers 应用,选择「Continue with GitHub」,选择 fork 的仓库;
  2. 在「Create and deploy」阶段,展开「Advanced settings」,将「Path」填写为 /apps/web;
  3. 添加以下环境变量:
    • NUXT_AI_AGENT_API_BASE_URL:Cloud Run 上的 Agent 根地址
    • NUXT_GOOGLE_SERVICE_ACCOUNT_JSON:将前文下载的服务账号 JSON 压成单行后写入(可用 jq -c . key.json)
  4. 点击「Deploy」;部署完成后,打开 Domains 标签页,打开生产用的 URL 开关,即可通过该地址访问。确认页面可打开,且 AI 能力可用。

更多文档

主题 文档
日常开发命令 docs/DEVELOPMENT.md
笔记 / Content 集成 docs/open-personal-note-integration.md
AI Agent API / codegen docs/ai-agent-api.md
Cloud Run 认证 docs/ai-agent-cloud-run-auth.md
CI / 部署 docs/CICD.md、docs/DEPLOY.md
Agent 包说明 apps/ai-agent/README.md

About

Nuxt Content blog template inspired by HugoRCD/canvas.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages