企业官网建设流程全解析

Lumen自托管部署教程：10分钟用Vercel发布你的专属笔记实例（含GitHub OAuth配置）

【免费下载链接】lumenA free, open-source note-taking app that syncs with markdown files in your GitHub repository项目地址: https://gitcode.com/gh_mirrors/lumen1/lumen

Lumen是一款免费、开源的笔记应用，它的笔记以 Markdown 文件形式同步到你自己的 GitHub 仓库中，数据完全由你掌控。本文带你完成Lumen 自托管部署：在 10 分钟内用 Vercel 发布一个专属笔记实例，并手把手配置GitHub OAuth，实现一键登录与仓库同步。

为什么选择 Lumen？

在部署之前，先花 30 秒了解它能给你带来什么：

• 📝纯 Markdown：无锁定的纯文本格式，任意编辑器都能打开
• 🔄GitHub 双向同步：基于 isomorphic-git，在浏览器中完成克隆、编辑、推送
• 🔗Wiki 链接 / 标签 / 模板：支持[[wikilink]]内链、标签聚合与模板变量
• 🤖AI 语音助手：可接入 OpenAI 进行语音对话
• 📱PWA 离线支持：移动端可安装到主屏使用

核心特性一览可在 README.md 中找到。

准备工作清单 📋

开始 Lumen 自托管部署前，请确认已准备好：

第一步：获取 Lumen 代码

克隆代码仓库（仓库地址如下）：

git clone https://gitcode.com/gh_mirrors/lumen1/lumen cd lumen npm install

💡 安装完成后会自动执行patch-package（见 package.json 的postinstall脚本），无需手动处理补丁文件 decode-named-character-reference+1.0.2.patch。

本地快速体验（开发模式下用个人访问令牌登录，跳过 OAuth）：

# 在根目录创建 .env.local # VITE_GITHUB_PAT=<你的个人访问令牌> npm run dev:vercel

然后访问http://localhost:8888。相关说明见 CONTRIBUTING.md。

第二步：用 Vercel 发布部署

1. 在 Vercel 中Add New → Project，导入上一步克隆的仓库

2. 框架自动识别为Vite，构建命令保持默认npm run build

3. 在项目Settings → Environment Variables中添加两个变量：

   • VITE_GITHUB_CLIENT_ID：OAuth App 的 Client ID
   • GITHUB_CLIENT_SECRET：OAuth App 的 Client Secret

4. 点击Deploy，约 1~2 分钟后即可访问你的专属笔记实例 🎉

为什么只需要两个变量？登录回调由服务端函数 api/github-auth.ts 处理，它用 Client ID + Secret 换取 access token，Secret 只存在于服务端，不会暴露给浏览器。

路由与代理是怎么配的？

无需手动配置：vercel.json 已预置所有重写规则，把/github-auth、/cors-proxy、/file-proxy等路径代理到api/目录下的函数（如 api/cors-proxy.ts、api/share/[...path].ts）。其中/cors-proxy负责绕过浏览器跨域限制，让 isomorphic-git 能直连 API 完成仓库读写。

第三步：配置 GitHub OAuth（关键）

这是自托管部署中最容易踩坑的一步，请按以下步骤操作：

1. 登录 Git 平台 →Settings → Developer settings → OAuth Apps → New OAuth App
2. Application URL：填写你的 Vercel 域名，如https://lumen.example.com
3. Authorization callback URL：填写https://lumen.example.com/github-auth⚠️ 必须与域名完全一致，否则登录会报redirect_uri错误
4. 保存后复制Client ID和Client Secret，填入 Vercel 环境变量
5. 重新部署一次使环境变量生效

前端登录按钮会请求repo,gist,user:email三个权限（scope），发起逻辑在 src/components/github-auth.tsx。

⚠️邮箱提示：OAuth 流程要求账号至少有一个公开的邮箱，否则会提示 "No public email found"。请在账号邮箱设置中取消隐藏至少一个邮箱（见 api/github-auth.ts 中的校验逻辑）。

首次使用：为实例选择一个笔记仓库

部署完成后，打开你的实例并点击Sign in with GitHub，授权通过后会出现仓库选择表单（组件源码：src/components/repo-form.tsx）：

• Select an existing repository：直接挂载已有的 Markdown 仓库
• Create a new repository：一键基于官方模板生成全新的私有笔记仓库

之后所有笔记都会作为.md文件写回仓库，包含 frontmatter 元数据（格式定义见 docs/metadata.md），你可以随时用任意编辑器离线修改。

常见问题排查 🛠️

写在最后

至此，你已完成一次完整的Lumen 自托管部署：一个只属于你（或你的小团队）的 Markdown 笔记实例已上线，笔记数据以纯文本形式存放在自己的仓库里——这才是"数据自由"的终极形态。

更多进阶内容可以参考：

• 查询语法：docs/query-language.md
• 模板变量用法：docs/templates.md
• 键盘快捷键速查：docs/keyboard-shortcuts.md

【免费下载链接】lumenA free, open-source note-taking app that syncs with markdown files in your GitHub repository项目地址: https://gitcode.com/gh_mirrors/lumen1/lumen