diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..c3579ff
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,52 @@
+---
+name: Bug 反馈
+about: 报告可复现的问题、报错、功能异常或回归
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## 问题现象
+
+请描述实际发生了什么。
+
+## 期望行为
+
+请描述你认为正确结果应该是什么。
+
+## 复现步骤
+
+1.
+2.
+3.
+
+## 部署方式
+
+- 部署方式：Docker 第一档 / 第二档 / 第三档 / 裸机 / 其他
+- 镜像或版本：
+- NAS / 系统：
+- Docker 版本：
+- Docker Compose 版本：
+- 浏览器：
+
+## 关键配置
+
+请贴出相关配置片段，例如路径映射、媒体库路径、下载器保存路径、站点类型等。
+
+请务必隐藏 Cookie、API Key、Passkey、密码、Token 和私有下载链接。
+
+```yaml
+# docker-compose.yml 相关片段
+```
+
+## 日志 / 任务详情
+
+请附上应用日志、任务队列详情、浏览器控制台错误或网络请求错误。
+
+```text
+
+```
+
+## 补充信息
+
+截图、录屏、相关 Issue、你已经尝试过的排查步骤。
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..1ca884d
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+ - name: Telegram MediaStationGo 交流群
+ url: https://t.me/MediaStationGo
+ about: 适合快速交流部署经验、使用问题和排查线索。
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..b7450df
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,29 @@
+---
+name: 功能建议
+about: 提出新功能、体验改进或兼容性需求
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## 需求背景
+
+这个功能解决什么问题？当前使用流程哪里不方便？
+
+## 期望方案
+
+请描述你希望 MediaStationGo 如何工作。
+
+## 使用场景
+
+- 部署环境：
+- 相关页面或模块：
+- 受影响用户：
+
+## 可接受的替代方案
+
+如果有其他实现方式或临时解决办法，也请写出来。
+
+## 补充信息
+
+截图、竞品参考、API 文档、相关讨论链接等。
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..75396b4
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,40 @@
+## 背景
+
+说明这个 PR 解决的问题、关联 Issue 或用户场景。
+
+> 请确认本 PR 基于本仓库最新 `main` 的独立分支或 fork 分支提交，未直接向 `main` 推送，也未夹带个人部署魔改配置。
+
+## 改动摘要
+
+-
+
+## 验证
+
+- [ ] `go test ./...`
+- [ ] `npm --prefix web run build`
+- [ ] `git diff --check`
+- [ ] 其他：
+
+## 风险与兼容性
+
+- 是否影响 Docker / NAS 路径映射：
+- 是否影响数据库迁移或数据结构：
+- 是否影响下载器、订阅、站点 API 或限流：
+- 是否包含敏感信息脱敏：
+
+## 截图 / 日志
+
+涉及 UI、任务队列、错误提示、设置页时请附截图或日志片段。
+
+```text
+
+```
+
+## 提交前检查
+
+- [ ] 分支已同步最新 `main`，不是直接在 `main` 上提交。
+- [ ] PR 范围聚焦，没有夹带无关重构。
+- [ ] 未提交个人部署配置、私有路径、API Key、Cookie、Token 或私有镜像标签。
+- [ ] 用户可见错误有清晰提示或日志。
+- [ ] 新行为有测试覆盖，或已说明无法覆盖的原因。
+- [ ] 文档、示例配置、README 已按需同步。
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..4da0548
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,114 @@
+# 贡献规范
+
+感谢你愿意帮助 MediaStationGo 变得更稳定。这个项目主要面向 NAS、Docker 部署、媒体库整理、订阅下载和多端播放场景；提交 Issue 或 Pull Request 时，请尽量提供可复现、可验证的信息。
+
+## Issue 提交规范
+
+提交 Issue 前，请先确认：
+
+- 已搜索现有 Issues，避免重复提交同一个问题。
+- 使用的是最新镜像、最新主分支，或已说明当前版本号 / 镜像摘要。
+- 如果是部署或运行问题，已附上部署方式和关键配置。
+
+### Bug Report 必填信息
+
+- 问题现象：实际发生了什么，是否稳定复现。
+- 期望行为：你认为正确结果应该是什么。
+- 复现步骤：从哪个页面、点击什么、填写什么、触发什么任务。
+- 部署方式：Docker 第一档 / 第二档 / 第三档、裸机运行、反代方式等。
+- 环境信息：NAS 型号或系统、Docker / Compose 版本、浏览器、MediaStationGo 镜像版本。
+- 相关配置：路径映射、下载器保存路径、媒体库路径、站点类型等。请隐藏 Cookie、API Key、密码和 Token。
+- 日志和任务信息：优先提供应用日志、任务队列详情、浏览器控制台错误、网络请求错误。
+
+### 日志建议
+
+排查订阅、站点搜索、下载器、整理入库、网盘扫描时，建议临时把日志级别调整为 `info` 或 `debug`，复现后再恢复。
+
+Docker 部署常用命令：
+
+```bash
+docker compose ps
+docker compose logs --tail=300 mediastation-go
+docker compose exec mediastation-go sh -lc 'ls -la /data/logs || true'
+```
+
+PostgreSQL 部署查询示例：
+
+```bash
+docker compose exec postgres psql -U mediastation -d mediastation -c "select key,value,updated_at from settings order by updated_at desc limit 30;"
+```
+
+请勿公开粘贴以下敏感信息：
+
+- 站点 Cookie、Passkey、API Key、YemaPT Auth Key、M-Team API Key。
+- qBittorrent / Transmission / Aria2 密码。
+- Telegram Bot Token。
+- JWT、数据库密码、私有下载链接。
+
+## Pull Request 提交规范
+
+所有非紧急变更都应通过 Pull Request 合入 `main`，不要直接向主分支推送。贡献者可以从 fork 或本仓库的独立分支发起 PR；维护者只有在紧急安全修复、发布流水线修复等特殊场景下，才可以短暂绕过 PR 流程，并需要在提交说明或后续 Issue 中补充原因。
+
+PR 应该尽量小而清晰。一次 PR 聚焦一个问题或一组强相关改动，避免把无关重构、格式化和功能混在一起。
+
+### 分支要求
+
+- 分支从最新 `main` 创建，提交前先同步远端主分支。
+- 分支名建议使用 `fix/...`、`feat/...`、`docs/...` 或 `test/...`。
+- 不要在 `main` 上直接开发和提交 PR 内容。
+- 不要把个人部署配置、NAS 本地路径、私有镜像标签或测试数据提交进 PR。
+- 如果基于魔改版、私有部署版或临时补丁开发，请先确认改动能在本仓库最新 `main` 上复现和应用，再提交 PR。
+
+### PR 描述应包含
+
+- 背景：修复哪个 Issue / 哪个用户场景 / 哪个回归。
+- 改动摘要：后端、前端、配置、文档分别改了什么。
+- 验证结果：运行过哪些命令，是否有无法运行的测试。
+- 风险说明：数据迁移、Docker 配置、路径映射、下载器行为、站点 API 限流等是否受影响。
+- 截图或录屏：涉及 UI、任务队列、错误提示、设置页时请附上。
+
+### 推荐验证命令
+
+根据改动范围选择运行：
+
+```bash
+go test ./...
+npm --prefix web run build
+git diff --check
+```
+
+如果只改动某个模块，可以先跑定向测试，例如：
+
+```bash
+go test ./internal/service -run "TestOrganize|TestSubscription|TestMTeam" -count=1
+go test ./cmd/server -count=1
+```
+
+### 代码要求
+
+- Go 代码使用 `gofmt`。
+- 前端 TypeScript 需要通过 `npm --prefix web run build`。
+- 用户可见错误需要可操作：说明失败原因、下一步怎么查或怎么修。
+- 后台任务失败不要静默吞掉，应进入任务队列、日志或 API 响应。
+- Docker/NAS 路径相关改动必须考虑宿主机路径与容器路径映射。
+- 站点 API、订阅和下载器改动需要注意去重、限流、敏感信息脱敏。
+
+## Commit Message 建议
+
+优先使用简短清晰的动词开头：
+
+```text
+fix organizer hardlink diagnostics
+feat(yemapt): add auth-only site adapter
+docs: add issue and pull request guidelines
+test: cover subscription restore matching
+```
+
+## 维护者合并检查
+
+合并前建议确认：
+
+- PR 范围清楚，没有夹带无关改动。
+- 自动化检查通过，或失败原因已说明。
+- 修改涉及的用户路径已有日志、错误提示或回归测试。
+- 文档、示例配置和 README 是否需要同步更新。
diff --git a/README.md b/README.md
index 26dcc04..04796d5 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@
路径映射 ·
旧 SQLite 迁移 ·
开发构建 ·
+ 贡献规范 ·
在线演示