# 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 配置。