96 lines
4.0 KiB
Markdown
96 lines
4.0 KiB
Markdown
# 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. 常用命令
|
||
|
||
```bash
|
||
npm install # 安装依赖
|
||
npm run dev # 本地开发预览（默认 http://localhost:4321）
|
||
npm run build # 构建到 dist/
|
||
npm run preview # 预览构建结果
|
||
```
|
||
|
||
## 7. 待办 / 路线图
|
||
|
||
- [x] 技术选型与方案确定
|
||
- [x] 工程骨架搭建
|
||
- [x] 首页 / 关于 / 项目 / 博客 / 联系页面
|
||
- [x] 暗色主题样式
|
||
- [x] 本地构建验证（`npm run build` 通过，8 页生成）
|
||
- [x] 在线内容管理方案确定（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 配置。
|