Initial commit

2026-07-05 17:59:02 +08:00
commit 11ea2ddb9a
18 changed files with 5549 additions and 0 deletions
@@ -0,0 +1,256 @@
+# Debian Docker 部署说明
+
+这份文档说明如何把 Daily News for Markyan04 部署到你的个人 Debian 服务器上，通过 Docker Compose 每天早上自动生成并发送日报。
+
+## 部署目标
+
+每天早上 08:00，按 `Asia/Shanghai` 时区执行：
+
+```text
+采集新闻 -> 生成中文日报 -> 归档到 newspaper/ -> 发送到 markyan04@163.com
+```
+
+收件人已经在 `config/delivery.yaml` 中配置为：
+
+```text
+markyan04@163.com
+```
+
+## 服务器前置条件
+
+服务器需要安装 Docker 和 Docker Compose plugin。
+
+Debian 常见安装方式：
+
+```bash
+sudo apt-get update
+sudo apt-get install -y ca-certificates curl gnupg
+sudo install -m 0755 -d /etc/apt/keyrings
+curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+sudo chmod a+r /etc/apt/keyrings/docker.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+sudo apt-get update
+sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+```
+
+如果希望当前用户直接运行 Docker，可以执行：
+
+```bash
+sudo usermod -aG docker "$USER"
+```
+
+执行后需要退出 SSH 并重新登录，用户组才会生效。
+
+## 复制仓库到服务器
+
+建议放到 `/srv/apps/newspaper`：
+
+```bash
+sudo mkdir -p /srv/apps/newspaper
+sudo chown -R "$USER":"$USER" /srv/apps/newspaper
+rsync -av --exclude .env /path/to/Newspaper/ /srv/apps/newspaper/
+cd /srv/apps/newspaper
+```
+
+如果你用 `scp`、`git clone` 或 Synology 同步目录，也可以，只要最终目录结构完整即可。
+
+## 创建 `.env`
+
+复制模板：
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+填写：
+
+```text
+DEEPSEEK_API_KEY=你的 DeepSeek API Key
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+DEEPSEEK_MODEL=deepseek-v4-pro
+GITHUB_TOKEN=可选，GitHub 只读 token，用于提高开源项目搜索限额
+
+NEWSPAPER_SMTP_HOST=smtp.163.com
+NEWSPAPER_SMTP_PORT=465
+NEWSPAPER_SMTP_USERNAME=你的发件邮箱
+NEWSPAPER_SMTP_PASSWORD=你的邮箱授权码
+NEWSPAPER_FROM_EMAIL=你的发件邮箱
+NEWSPAPER_FROM_NAME=Daily News for Markyan04
+NEWSPAPER_SMTP_SECURITY=ssl
+
+NEWSPAPER_SCHEDULE_TIME=08:00
+TZ=Asia/Shanghai
+```
+
+注意：
+
+- 如果使用 163 邮箱发件，需要在邮箱设置中开启 SMTP/IMAP 服务。
+- `GITHUB_TOKEN` 可以留空；如果 GitHub / 开源项目栏目经常空白，建议填一个只读 token。
+- `NEWSPAPER_SMTP_PASSWORD` 应填写邮箱授权码，不是网页登录密码。
+- 如果使用其他邮箱或邮件服务商，请按服务商文档替换 SMTP host、port 和 security。
+- 不要把 `.env` 提交到仓库，也不要把授权码发到聊天里。
+
+## 构建镜像
+
+```bash
+docker compose build
+```
+
+## 检查配置
+
+```bash
+docker compose run --rm newspaper hongyu-daily check-config
+```
+
+期望输出：
+
+```text
+config/newspaper.yaml: OK
+config/sources.yaml: OK
+config/delivery.yaml: OK
+newspaper archive: newspaper/
+```
+
+## 只生成日报，不发送
+
+```bash
+docker compose run --rm newspaper hongyu-daily generate
+```
+
+检查归档目录：
+
+```bash
+ls -lh newspaper/
+```
+
+应该看到：
+
+```text
+YYYY-MM-DD-daily-news-for-markyan04.md
+YYYY-MM-DD-daily-news-for-markyan04.html
+YYYY-MM-DD-daily-news-for-markyan04.meta.json
+```
+
+建议第一次先打开 `.md` 或 `.html` 检查：
+
+- 正文是否为中文。
+- 每条新闻是否有来源链接。
+- 新闻是否带有发布时间、更新时间或采集时间。
+- AI 栏目是否是新鲜内容，而不是旧概念拼贴。
+- 传统新闻是否覆盖了真实的新进展，而不是泛泛复述旧背景。
+
+## 发送已生成的日报
+
+如果你已经生成了某一天的日报，可以单独发送：
+
+```bash
+docker compose run --rm newspaper hongyu-daily send --date YYYY-MM-DD
+```
+
+例如：
+
+```bash
+docker compose run --rm newspaper hongyu-daily send --date 2026-07-04
+```
+
+## 生成并发送一次
+
+```bash
+docker compose run --rm newspaper hongyu-daily run
+```
+
+这个命令会完成：
+
+```text
+采集 -> 生成 -> 归档 -> 发送
+```
+
+## 启动每日定时任务
+
+```bash
+docker compose up -d scheduler
+```
+
+查看日志：
+
+```bash
+docker compose logs -f scheduler
+```
+
+`scheduler` 服务会常驻运行，每天本地时间 08:00 执行一次。
+
+## 停止每日定时任务
+
+```bash
+docker compose down
+```
+
+## 可选方案：使用 Debian 主机 cron
+
+如果你不想让 `scheduler` 容器常驻，也可以用 Debian 主机的 cron。
+
+先创建日志目录：
+
+```bash
+mkdir -p /srv/apps/newspaper/logs
+```
+
+编辑 crontab：
+
+```bash
+crontab -e
+```
+
+加入：
+
+```text
+0 8 * * * cd /srv/apps/newspaper && docker compose run --rm newspaper hongyu-daily run >> logs/cron.log 2>&1
+```
+
+注意：不要同时启用主机 cron 和 `scheduler` 容器，否则每天可能会重复发送。
+
+## 更新部署
+
+当你把新代码复制到服务器后：
+
+```bash
+cd /srv/apps/newspaper
+docker compose build
+docker compose up -d scheduler
+```
+
+如果只想手动跑一次：
+
+```bash
+docker compose run --rm newspaper hongyu-daily run
+```
+
+## 常见问题
+
+### Docker 构建失败
+
+先确认服务器能访问 Python 包源和 Debian 软件源。
+
+```bash
+docker compose build --no-cache
+```
+
+### 邮件发送失败
+
+优先检查：
+
+- SMTP host 和 port 是否正确。
+- `NEWSPAPER_SMTP_SECURITY` 是否应为 `ssl` 或 `starttls`。
+- 邮箱是否开启 SMTP/IMAP。
+- `NEWSPAPER_SMTP_PASSWORD` 是否是授权码。
+- 服务器是否允许连接 SMTP 端口。
+
+### 生成日报失败
+
+优先检查：
+
+- `DEEPSEEK_API_KEY` 是否正确。
+- DeepSeek API 账户是否有额度。
+- 服务器是否能访问 `https://api.deepseek.com`。
+- `config/sources.yaml` 中的来源是否大面积无法访问。