jiang13-forum/docs/rebuild-spec/07-config-ops.md

07 · 配置、运维与 SEO

读者：部署与运维、以及实现配置层的 AI
前置：README.md
源码：app.ini.example、config/、README.md、handler/seo.go、handler/seo_bot.go、embed_static/

运维形态可改；下列描述现网行为，便于迁移数据与对齐环境变量语义。

---

1. 进程配置优先级

命令行显式参数 > 环境变量 > app.ini > 内置默认

CLI	环境变量	INI	默认	说明
--port	JIANG13_HTTP_PORT	[server] HTTP_PORT	3000	监听端口
--data	JIANG13_DATA	[paths] DATA	data	数据目录
--jwt-secret	JIANG13_JWT_SECRET	[security] JWT_SECRET	自动生成	JWT 密钥
--config	JIANG13_CONFIG		{work}/app.ini	配置文件路径
--work-path	JIANG13_WORK_PATH		可执行文件目录	工作目录
--service				install/uninstall/start/stop/restart/status

app.ini 示例见 app.ini.example。业务配置（邮件、OIDC、Gitea、存储、品牌等）在 DB forum_settings，管理后台热更新，不必写进 ini。

---

2. 数据目录结构

data/
├── jiang13.db              # SQLite 主库
├── jiang13.log             # 运行日志
├── filter_words.txt        # 敏感词
├── .jwt_secret             # 自动生成的 JWT 密钥（勿提交仓库）
├── uploads/
│   ├── avatars/
│   ├── posts/
│   └── site/               # 品牌资源等
└── jiang13_backup_*.db     # 后台导出备份

开发时后端常与 dist/data 共用，避免 dev 与产物数据分裂（见根 README）。

---

3. 部署方式（现网）

方式	说明
单二进制	build.bat / make build → dist/jiang13(.exe)
Docker	镜像挂载 /data；健康检查 GET /health
Compose	docker compose up -d --build
systemd / Windows Service	--service install 后启停

构建约定见 .cursor/rules/build-scripts.mdc：Windows 用 build.bat，勿直接 make / .\build.ps1。

容器常用环境变量与上表 JIANG13_* 一致。旧镜像权限问题：数据目录属主 uid 1000。

---

4. 存储后端

type	行为
local	文件落在 data/uploads；URL 通常 /uploads/...
s3	S3 兼容；endpoint、bucket、密钥、public_base_url、prefix、force_path_style

image_delivery：webp（默认，经 /media/thumb）或 original。上传始终可保留原图策略以实现为准。

媒体索引表 media 供后台列表；启动时可后台 SyncMediaIndex。

---

5. SEO / 社交分享字段集合

新站应用真 SSR，但 meta 字段应对齐：

字段	来源
<title>	站点 DocumentTitle 或帖标题
meta description	站点简介优先，否则标语；帖文则摘要
meta keywords	站点 keywords
canonical	绝对 URL
og:type / site_name / locale / title / description / url / image
twitter:card / title / description / image
JSON-LD	结构化数据（站点或 Article）
robots	个别页可 noindex（以实现为准）

现网额外机制（可废弃）

机制	说明
SPA 壳注入	embed_static 注入 title / branding JSON，无帖文 DOM
爬虫 HTML	User-Agent 命中时 seo_bot.go 返回简易 HTML
robots.txt / sitemap.xml	动态生成

重构验收：用普通浏览器「查看网页源代码」应能看到帖文正文，而不仅是空 div + script。

---

6. 伪静态 Permalink

设置：permalink_enabled、permalink_ext（默认 html）。

规范路径示例：

• /post/123.html
• /user/1.html
• /board/2.html
• /page/about.html

路由应同时接受无后缀与有后缀形式。解析逻辑见 service/permalink.go。

---

7. 安全相关运维注意

项	说明
JWT 密钥	生产必须固定且保密；勿提交 .jwt_secret
Cookie	jiang13_token HttpOnly；生产应 Secure + 合适 SameSite
上传	类型/大小限制（头像 MB、帖图策略）
敏感词	后台可改；影响发帖评论私信等
OAuth 密钥	仅存 bcrypt 哈希；创建时明文只回显一次
备份	含用户哈希与私信，下载需管理员权限、传输加密

---

8. 健康检查

GET /health → JSON status。Docker / 负载均衡探活依赖此接口；实现应在 DB 不可用时返回非 200。

---

9. 从旧站迁数据建议

1. 导出 / 复制 jiang13.db（或 dump 到新库并映射表）
2. 复制 uploads/ 与 filter_words.txt
3. 迁移 forum_settings 键值（或后台重新配置）
4. 会话：旧 JWT 密钥兼容一阶段，或强制全员重登
5. OIDC 客户端：oauth_clients 表 + 重新下发密钥（若无法迁移哈希）

表语义以 03-data-model.md 为准。

---

10. 文档包索引

返回 README.md 阅读顺序；功能验收用 02-features.md；规则用 05-business-rules.md。