4.0 KiB
4.0 KiB
ShiZhui 网站 项目文档
本文档记录项目的方案、技术选型、结构与运维信息，随项目推进持续更新。
1. 项目概述
- 域名：shizhui.xyz（已可 ping 通）
- 定位：展示型网站（作品集 / 产品展示），非运营、非社交
- 内容方向：电子工程、软件工程、通信、机器人类产品
- 维护者背景：嵌入式工程师，Web 经验较少，需求是"结构清晰、长期可增量维护"
2. 技术选型
| 项 | 选择 | 说明 |
|---|---|---|
| 站点类型 | 静态站点（SSG） | 无后端、无数据库，安全面小、易运维 |
| 框架 | Astro 5 | 语法接近 HTML，组件化，内容用 Markdown，将来可按需加交互组件 |
| 内容 | Markdown / MDX | 博客与项目内容用 Markdown 编写，便于维护 |
| 样式 | 原生 CSS（CSS 变量主题） | 工程/极简科技风，暗色调，无重型 UI 框架 |
| 语言 | 中文为主 | |
| 部署 | Nginx 托管静态文件 | Ubuntu 26 服务器 |
| HTTPS | Let's Encrypt（certbot） | 免费证书，自动续期 |
| 内容管理 | Gitea + Sveltia CMS | 自托管 Git + 在线写作后台，详见 docs/CMS.md |
设计风格
- 工程 / 极简科技风
- 暗色调为主
- 强调可读性与信息密度
3. 站点板块
- 首页（Home）：简介 + 精选项目/文章入口
- 关于（About）：个人/团队介绍、技能方向
- 项目 / 产品（Projects）：硬件/软件/通信/机器人作品展示
- 技术博客（Blog）：技术文章
- 联系方式（Contact）
4. 工程结构
shizhui_website/
├── docs/ # 项目文档（本目录）
│ ├── PROJECT.md # 项目总览（本文件）
│ └── DEPLOY.md # 部署与运维记录
├── public/ # 静态资源（直接拷贝，不经构建）
├── src/
│ ├── components/ # 复用组件
│ ├── layouts/ # 页面布局
│ ├── pages/ # 路由页面（文件即路由）
│ ├── content/ # Markdown 内容集合（blog / projects）
│ └── styles/ # 全局样式与主题变量
├── astro.config.mjs # Astro 配置
├── package.json
└── tsconfig.json
5. 内容维护方式（给非前端的你）
- 加一篇博客：在
src/content/blog/新建一个.md文件，填好顶部 frontmatter（标题、日期、摘要），写正文即可。 - 加一个项目：在
src/content/projects/新建一个.md文件，填好 frontmatter（名称、分类、简介、链接），写详情即可。 - 改完后本地
npm run build，再部署。
6. 常用命令
npm install # 安装依赖
npm run dev # 本地开发预览（默认 http://localhost:4321）
npm run build # 构建到 dist/
npm run preview # 预览构建结果
7. 待办 / 路线图
- 技术选型与方案确定
- 工程骨架搭建
- 首页 / 关于 / 项目 / 博客 / 联系页面
- 暗色主题样式
- 本地构建验证（
npm run build通过，8 页生成） - 在线内容管理方案确定（Gitea + Sveltia CMS，见
docs/CMS.md） - 服务器环境部署（Nginx + HTTPS）
- 自托管 Gitea + Sveltia CMS 在线编辑后台
- 域名解析与上线
已实现功能
- 响应式暗色主题（CSS 变量，工程/极简科技风）
- 内容集合：
blog（博客）+projects（项目），均用 Markdown + frontmatter - 项目页支持按分类（硬件/软件/通信/机器人）前端筛选
- 博客 RSS 订阅（
/rss.xml）、站点地图（sitemap）、SEO 与 OG 标签 - 站点信息集中在
src/site.config.ts（标题、导航、社交链接、邮箱）
8. 安全备注
- 务必尽快更换服务器 root 密码，并改用 SSH 密钥登录、关闭密码登录。
- 凭据不写入仓库与文档（本文件不记录任何密码）。
- 静态站点无后端，攻击面主要在服务器 SSH 与 Nginx 配置。