TimeAmber

高质感自托管个人博客系统

极致视觉 · 树莓派生产部署 · PostgreSQL · 本地媒体存储

文档 · 在线站点 · 反馈 · 安全 · 隐私

TimeAmber 是一套现代化个人博客系统，当前生产站点运行在树莓派 Docker Compose 环境中：Hono Node 服务负责 API 与静态资源，PostgreSQL 持久化内容，本地文件系统保存媒体资源，并通过现有域名链路对外服务。

设计哲学：内容优先 · 自主托管 · 沉浸式阅读。

• 沉浸式编辑器：Markdown + 实时预览，KaTeX 数学公式，代码高亮一键复制。
• 多平台导入：支持 WordPress / Ghost / Hexo / Hugo / Jekyll / Halo，也支持后台批量导入 Markdown。
• AI 辅助编辑：后台可配置 DeepSeek / Gemini / OpenAI Compatible，在文章编辑页预览并应用 AI 修改结果。
• 内容编排：草稿、定时发布、置顶、系列合集、独立页动态导航。
• 友链管理：前台独立友链页，后台可维护名称、地址与 Logo。

• 暗/亮双主题：OKLCH 色值系统，过渡顺滑无闪烁。
• 统一品牌图：README 图标、favicon、PWA icon 与默认 OG 图统一使用最新版 TimeAmber 图标。
• 稳定文章列表：文章卡片固定行高，封面图不会撑破列表布局。
• 文章导航：自动 TOC、阅读进度条、IntersectionObserver 章节追踪。
• 全站搜索：防抖检索、键盘导航、关键词高亮。
• Reaction 表情：文末轻互动，无需登录即可表态。

• 树莓派自托管：Hono + Node.js 运行时，Docker Compose 管理应用与 PostgreSQL。
• 持久化存储：当前生产使用 PostgreSQL 16 与本地文件系统媒体存储。
• 多后端适配：代码仍保留 D1 / Turso / PostgreSQL 与 R2 / S3 兼容存储适配。
• 访客统计：当前树莓派 PostgreSQL 部署使用基础统计，后台不再展示 Cloudflare 专属分析入口。
• 归档同步：同机 vs.do 服务向 TimeAmber 写入归档文章。

• 认证与防护：JWT + 限流，CSP/HSTS 安全头，SSRF 拦截。
• 隐私优先：Cookie 同意横幅，第三方脚本门控，GDPR 数据导出。
• 备份与媒体：JSON / R2-S3 / WebDAV 备份能力保留；当前生产媒体存储位于树莓派本地目录。
• 外链图片托管：保存文章或批量导入 Markdown 时，可自动将外部图片上传到 S.EE，并用 https://i.see.you/... 直连覆盖正文链接。
• Notion 同步：可从指定 Notion 数据库同步文章，首次进入草稿，站内发布状态不被 Notion 更新覆盖。

本仓库当前维护的是 TimeAmber 线上站点：timeamber.com。项目名、前后台标识、README 图标、favicon 和 PWA 图标已统一为 TimeAmber 最新品牌资源。

• 品牌资源：README 顶部图标、favicon、PWA icon 与默认 OG 图统一使用仓库内最新版 client/public/timeamber-icon.png / icon-192.png / icon-512.png。
• 树莓派部署：生产代码已同步到上游 v2.5.0，并保留 TimeAmber 品牌、PostgreSQL、本地媒体存储和 vs.do 归档集成。
• 文章列表：文章卡片高度固定，封面图被限制在卡片行高内，避免列表跳动。
• 文章正文：长链接、原文地址、引用块和表格单元格必须在内容栏内自动换行，不能横向溢出或覆盖右侧目录。
• Markdown 导入：后台支持批量导入 Markdown；导入后默认草稿，可在列表批量发布，也可进入单篇编辑页单独发布。
• 友链：导航栏新增 /friends 友链入口，后台 站点设置 -> 友链 可自定义名称、地址与 Logo。
• S.EE 图床：后台 站点设置 -> 图片托管 可开启自动上传外部图片；已托管的 i.see.you / s.ee 链接会跳过，S.EE 返回的直连会原样写入文章。
• Notion 同步：后台 站点设置 -> Notion 同步 可查看最近同步状态并手动触发；站内删除 notion-* 文章后会记录删除标记，Notion 中仍存在也不会再次创建。
• AI 编辑：后台 站点设置 -> AI 编辑 可配置 DeepSeek、Gemini 或 OpenAI Compatible API Key。
• SEO 域名：sitemap、robots、RSS 与前后台 SEO 面板使用 https://timeamber.com。

• GitHub Actions 只保留检查、发布说明和依赖维护流程；推送 main 不会触发生产发布。
• 当前生产发布以树莓派 Docker Compose 为准。
• Notion 同步需要在树莓派 /opt/timeamber/.env 配置 NOTION_TOKEN，并要求 Notion 数据库已分享给对应 Integration。
• 剪藏同步会从同机 vs.do 服务拉取文章并写入站内 VS.DO 剪藏 分类；需要在树莓派环境文件中配置 VS_DO_TOKEN。

┌─────────────────────────────────────────────────────────────────┐
│                         timeamber.com                           │
│        Cloudflare DNS / VPS reverse proxy / FRP ingress          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Raspberry Pi / Docker Compose                 │
│                                                                 │
│  ┌─────────────────────────────┐     ┌────────────────────────┐  │
│  │ timeamber-app               │     │ timeamber-postgres     │  │
│  │ Hono Node runtime           │────▶│ PostgreSQL 16          │  │
│  │ React static assets         │     │ /opt/timeamber/postgres│  │
│  │ Public/Admin API            │     └────────────────────────┘  │
│  │ /cdn local media route      │                                  │
│  └──────────────┬──────────────┘                                  │
│                 │                                                 │
│                 ▼                                                 │
│  ┌─────────────────────────────┐     ┌────────────────────────┐  │
│  │ /opt/timeamber/storage      │     │ /opt/web-archive       │  │
│  │ local media/object storage  │     │ vs.do archive service  │  │
│  └─────────────────────────────┘     └────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

• 适配器模式：数据库与对象存储均实现统一接口（IDatabase / IObjectStorage），切换后端零侵入。
• Node 静态托管与 API 同源：同一服务处理静态资源、/api/* 与 /cdn/*，规避 CORS 复杂度。
• Drizzle ORM：所有 SQL 参数化，Schema 一处定义、三端同步生成。
• Compose 生产部署：docker-compose.rpi.yml 管理应用服务、PostgreSQL、端口映射和持久化目录。

git clone https://github.com/NextCandy/TimeAmber.git
cd TimeAmber
npm install
npm run dev

完整环境准备、密钥配置与本地数据库初始化请参阅 Wiki · 快速开始。

ssh [email protected] -p 22370
cd /opt/timeamber/app
docker compose -f docker-compose.rpi.yml ps
docker compose -f docker-compose.rpi.yml up -d --build
curl -fsS http://127.0.0.1:49287/api/health

生产密钥只保存在树莓派 /opt/timeamber/.env，不要提交到仓库。只改 README、文档或 GitHub workflow 时无需重建容器；改动前后端代码时再执行 up -d --build。

欢迎通过 Issue 反馈问题，或通过 Pull Request 贡献代码。提交前请阅读 Wiki · 贡献指南。

基于 MIT License 开源发布。