Posts on 牙刷刷的小站

NT创意图志：一张图说清核心资产，家庭用户的好帮手

Sat, 12 Jul 2025 17:42:38 +0800

⚠️ 免责声明
本页面所展示的所有图片均由 Google Gemini 人工智能模型生成，基于用户输入的提示词自动合成，非人工拍摄或真实事件记录。图片内容仅用于视觉创意参考，不代表真实人物、地点、产品或事件，亦不构成任何形式的建议或承诺。

根据 Gemini 使用条款及其内容政策，所生成图片的版权归 Google 所有或依据其授权生成，使用者需自行判断并遵守相关法律法规，不得用于违反版权、商标或肖像权的商业用途。

若对生成内容有疑问或需移除，请通过页面下方方式与我们联系。

取得联系（Google Mail）：wth88888888

我的智能小助手 3.0：打造一间全自动化的“时光放映室”

Sat, 12 Jul 2025 17:10:27 +0800

欢迎回到我的“偷懒”摄影系统系列。在之前的篇章里，我们一起见证了一个普通摄像头如何被赋予“思考”的能力，以及如何为它建造一间优雅、便捷的“控制室”。然而，故事并未就此落幕。我们那个聪明的摄影师，每天都在聪明地“偷懒”，为我们精准地捕捉了海量、充满价值的瞬间。这些照片，如同一颗颗散落的珍珠，蕴含着时光的秘密，静静地躺在服务器的硬盘深处。

是时候了，我们该把这些珍珠串联起来，让它们在光影的流动中，绽放出璀璨夺目的光芒。今天，我将向大家展示这个项目的最终章，也是我个人认为最激动人心的部分——打造一间全自动化的“时光放映室”。这个放映室的核心，是一个强大而可靠的Shell脚本。它是我整个系统的“幕后总导演”，肩负着神圣的使命：在每个寂静的黎明到来之前，将过去一天的万千照片，自动合成为一部部精彩纷呈的延时影片。

项目代码：https://github.com/AndroidOL/camera-capture/tree/main/merge

从“素材堆积”到“影像诗篇”：最后的“亿”步

想象一下，如果没有这位自动化的“总导演”，我的生活将是怎样一番景象？那将意味着，每天，我都需要像一个数字时代的“矿工”，手动登录到远程服务器，在前一天产生的、可能多达几十GB的成千上万张照片中进行挖掘；然后，将这些“原矿”小心翼翼地下载到本地电脑；接着，再启动复杂的视频编辑软件，将这些照片一张张拖入时间线， painstaking 地设置帧率、编码器、码率……最后，在漫长的等待中，点击“渲染”按钮。

这整个过程，不仅是一场与耐心和毅力搏斗的、毫无创造性可言的机械劳动，更可怕的是，它极易出错。万一哪天我忘了，或者因为工作繁忙而错过，那天的“影像日记”就会出现一个无法弥补的空白。这不是我想要的。

我需要的是一个完全无人值守、极致稳定可靠、并且足够聪明的自动化流程。它应当是一位不知疲倦的艺术家，在每天固定的时间，比如万籁俱寂的凌晨，悄然启动，像一位技艺高超的电影剪辑师，将过去一天的零散素材，精心编排成一部完整的影片，然后优雅地将其安放于“家庭影片库”的数字货架上，静候我的检阅。

于是，这个倾注了我大量心血的自动化脚本——daily_photo_to_video.sh 应运而生。它远非一个简单的ffmpeg命令封装，而是一个拥有工业级健壮性的“智能生产线”。

“总导演”的超凡技艺：揭秘自动化脚本的核心设计

这个脚本的设计哲学，是**“追求极致的稳定与高效”**。我将它武装到了牙齿，让它能从容不迫地应对各种可以预见的、甚至难以预见的复杂状况。

1. 效率的极致：榨干硬件的每一分潜力

高速公路 - Ramdisk (内存盘)
直接在传统硬盘上读取上万张零散的小图片，同时写入一个巨大的视频文件，磁盘I/O（读写）的瓶颈会立刻显现，整个过程将变得异常缓慢。我的解决方案堪称激进：在服务器宝贵的内存中，直接开辟出一块高速的虚拟硬盘（Ramdisk）。

脚本启动后，会首先将所有待处理的照片，从拍照服务器通过网络高速同步到这块内存盘上。随后，视频合成（编码）的所有密集读写操作，也全部在这块虚拟硬盘内完成。内存的读写速度是普通硬盘的数十倍甚至上百倍，这无异于为数据的迁徙铺设了一条无视物理定律的、光速穿梭的“星际公路”，极大地缩短了处理时间。

专业引擎 - 硬件编码 (HEVC_RKMPP)
视频编码是典型的计算密集型任务，纯靠CPU来“硬算”，就像让一位全能但劳累的管家去做一件极其专业的木工活，不仅效率低下，还会让服务器的“心跳”（CPU占用率）飙升，风扇狂转。幸运的是，我所使用的服务器（基于Rockchip芯片）拥有专门的视频处理单元（VPU）。

我的脚本会精准地调用ffmpeg，并指定使用hevc_rkmpp这个硬件编码器。这相当于把专业的工作，交给了那位专门聘请的、技艺高超的“电影剪辑师”，让VPU来承担最繁重的编码任务，从而彻底解放了CPU。同时，我选择了高效的HEVC (H.265) 编码格式，它能在保持极高质量画面的同时，将视频体积压缩到传统H.264的一半左右，为我的“家庭影片库”节省了海量的宝贵空间。

2. 稳定性的基石：工业级的容错与自愈

在无人之境中独自航行的飞船，其价值不仅在于速度，更在于它应对宇宙风暴的生存能力。同样，一个需要常年无人值守的脚本，“逆商”至关重要。我为它构建了四重“安全协议”，来应对各种可能发生的意外。

场景	脚本的智能应对策略
脚本意外中断	使用`trap`清理机制，在中断时自动清理临时文件并卸载Ramdisk
同时运行冲突	使用`flock`文件锁机制，避免多实例并发执行冲突
存储空间不足	提前检查目标路径剩余空间，避免写入中途失败
目标硬盘掉线	自动切换至备用存储路径，保障任务完成并暂停旧任务追赶

3. 智慧的调度：绝不错过任何一天的精彩

我希望我的“放映室”里，每一天的影片都是完整的，如同一部连贯的编年史。因此，脚本最智能、最让我引以为傲的部分，在于它那近乎偏执的“补全”逻辑。

脚本运行时会：

回顾过去7天的日志，检查是否有影片缺失或失败；
若发现遗漏，优先从最早的那天开始补；
二次验证远程素材是否还在，确保不会空转；
若全部完整，才处理“昨天”的新素材。

这样，系统就拥有了记忆与责任感，始终维持一份完整的“影像日记”。

一部“家庭史诗”的诞生

现在，这已经成为一种充满仪式感的日常。每天清晨，当我泡好咖啡，打开“家庭影片库”时，一部全新的、以昨天日期命名的延时影片已经静静地躺在那里了。

它可能记录了窗外雷阵雨的全过程，也可能捕捉了我加班至深夜的身影，又或只是平淡地描绘阳光在家中流转的痕迹。

这个自动化脚本，就像一个沉默而强大的心脏，为我整个智能摄影项目注入了源源不断的生命力。它将日复一日的、琐碎的视觉信息，升华为一部部浓缩了时间精华的影像诗篇，将冰冷的数据，提炼成了有温度的记忆，让我真正得以“看见”并“珍藏”那些无声流逝的时光。

创造的乐趣

创造的乐趣，就在于此——用代码和逻辑，去构建一个能自动为我们创造、整理和呈现美好的系统。

下一步，或许是训练一个AI，让它能自动为这些影片配上最契合的背景音乐，或者剪辑出“每周精华”了。

这条通往“更好生活”的创造之路，永无止境，而这，也正是其魅力所在。

我的智能小助手 2.0：给“偷懒”摄影系统开了扇全景落地窗

Sat, 12 Jul 2025 16:19:04 +0800

距离上次分享我的“偷懒”摄影系统已经有段时间了，那个会自己判断何时该拍照、何时该“摸鱼”的小家伙，已经默默地为我工作了很久。但随着时间的推移，一个新的“痛点”开始浮现：尽管它内部很智能，但与它交流的方式却很“原始”。

项目代码：https://github.com/AndroidOL/camera-capture/tree/main/web-ui

从“命令行考古”到“指尖轻触”：一次体验的革命

在过去，每一次与它的互动，都像是一场深入服务器内部的“数字考古”之旅。

想看看昨天拍到了什么？请启动 SSH 客户端，连接服务器，用 cd 和 ls 命令在迷宫般的目录结构里穿行。
想调整拍摄的灵敏度参数？请用 Vim 或 Nano 修改配置文件，保存后再 systemctl restart，祈祷没改错字符。

这种体验繁琐且充满距离感。我的智能助手，它的喜怒哀乐、它的工作成果，都被一层名为“命令行”的黑盒子包裹着。

于是，我为它开了一扇窗：一扇能让我窝在沙发上，用最直观、最优雅方式与它交流的全景落地窗 —— 一个专属的网页控制台。

现在，一切都不同了：

打开浏览器，输入本地地址；
一个美观、强大的界面展现在眼前；
那个沉默的后台摄影师，拥有了鲜活的“面容”和灵巧的“双手”。

它的组成：

眼睛：实时监控窗口，无延迟。
双手：按钮菜单，一点即控。
大脑：复杂逻辑隐藏，美观又直观。

网页控制台的四大“超能力”

1. 时光抽屉：层级式的照片档案馆

灵感来自现实世界的“抽屉”。整个交互过程如同打开俄罗斯套娃般：

年度 / 月度：查看所有有记录的月份。
具体日期：以预览图展示每一天。
小时抽屉：点击后看到 24 小时分布。
分钟级照片：深入找到具体照片。

探索照片变得轻松、有趣、富有仪式感。

2. 实况视窗：永不眨眼的忠诚守望者

点击“实时监控”，系统立刻进入守望状态。

心跳刷新：前端每 2.5 秒请求一次画面，保持实时。
智能重连：摄像头掉线自动恢复。
夜间模式：环境变暗自动降亮，夜晚不刺眼。

3. 时光隧道：私人定制的纪录片生成器

“照片轮播”模式是我最爱的功能。

选择任意日期范围（如“2025 樱花季”）；
系统串联该时段所有照片，生成动态影片。

特点：

幻灯片模式：按时间顺序排列。
过渡效果：淡入淡出自然切换。
时间字幕：底部自动显示拍摄时间。

🎞️ 我就用它回顾了樱花从花苞到飘落的全过程，感动与震撼并存。

4. 明眸善睐：体贴入微的智能主题

我是夜猫子，因此加入了主题切换功能：

日间模式：蓝白配色，清爽。
暗夜模式：墨黑 + 绛红，护眼不扰人。
自动记忆：会记住你上次用的主题。

就像一个懂你的老朋友。

开发中的小剧场：让系统更“人性化”的瞬间

午夜惊魂记

某次深夜调试实时监控，画面疯狂刷新！原来我写成了 250ms 而不是 2500ms，摄像头差点变“机关枪”。

命名的灾难

最初 API 叫 get_image_list，我自己隔了段时间也完全看不懂。

生活的新视角：科技融入日常

网页控制台让摄影系统真正融入我的生活：

☕ 清晨咖啡时间：配延时画面唤醒一天；
🌱 植物生长日记：每周定期用“时光隧道”回顾变化；
🖼️ 家庭时光机：家庭聚会时投屏播放美好回忆。

给创造者的邀请函

打造这个系统，其实不难：

# ----- 基础装备 -----

# 硬件：树莓派 / 任意 Linux 设备 + 摄像头
# 图像分析：Python + OpenCV
# 前端界面：HTML + JavaScript + CSS
# 后端服务：PHP

每个模块都像一块乐高积木，你可以自由组合、修改、扩展。

技术的温度，在于我们如何用它去记录和照亮生活。期待你也能为生活打开一扇独特的“时光之窗”。

我的智能小助手：一个会“偷懒”的延时摄影系统

Sat, 12 Jul 2025 15:38:51 +0800

生活中那些安静流淌、不易察觉的诗意总是令人充满好奇。迷上了延时摄影因为它能将漫长的时间压缩成迷人的瞬间，让我们得以用肉眼观察到那些缓慢发生的变化，这本身就像一种时间的魔法。

于是，我翻出了家里那个在抽屉里沉睡了数年的 USB 摄像头，心中涌起一个温柔的念头：我想用它来记录，记录那些被我们匆忙忽略的、生活本身的呼吸。比如阳台上那盆多肉，如何在阳光的亲吻下，用我们看不见的速度悄悄舒展；窗外的云朵，又是如何被无形的手塑造成流动的雕塑；甚至是傍晚时分，夕阳如何在客厅的地板上，一寸寸地拉出长长的、温暖的影子……

项目代码：https://github.com/AndroidOL/camera-capture

从“勤奋的笨蛋”到“聪明的懒汉”：一次理念的进化

最开始，我的想法和大多数人一样，简单而直接：写一个脚本，让摄像头化身为一个不知疲倦的“劳动模范”，每分钟准时打卡，忠实地拍下一张照片。当我敲下最后一行代码并成功运行的那一刻，心中充满了小小的成就感。然而，这份喜悦在第二天清晨，当我检视成果时，便迅速被一种混杂着困惑与失望的复杂情绪所取代。

硬盘里，一千四百四十张照片整齐地排列着，它们是我的程序“勤奋”一整天的见证。但我快速滚动预览时，画面却像卡住了一样，静止得令人窒息。尤其是在那漫长的深夜时段，凌晨三点和三点零一分的客厅照片，别说茶几上的灰尘纹丝未动，就连空气本身，似乎都凝固在了那一刻。我忽然意识到，我创造的不是一个记录“变化”的工具，而是一个生产“重复”的工厂。

当我冷静下来，把这笔“数字遗产”量化后，我才真正理解了问题的严重性：

惊人的存储消耗：

日产量: 43200 张照片
月产量: 约 1296000 张照片
年产量: 超过 473040000 张照片

按每张照片分辨率 1920*1080 存储，每张照片占用大小 0.2MB 计算，每天将消耗近 8GB 的存储空间，对于家庭存储而言这并不算什么。但是对于嵌入式设备，ESP32 抑或是 RK 的单板机而言有点超出限制。

毁灭性的后期工作：

素材筛选: 为了剪辑出几分钟的精彩视频，需要在数十万张几乎相同的“废片”中大海捞针。
时间成本: 这哪里是艺术创作，分明是一场能耗尽所有热情的体力劳动。

为了更直观地展示这两种思路的差异，我做了一个简单的对比：

特性	“勤奋的笨蛋”模式	“聪明的懒汉”模式
工作原则	无差别、定时记录	智能判断、按需记录
每时照片数量	恒定 1800 张	几十到几百张不等，视变化而定
存储友好度	极低，呈线性爆炸增长	极高，只为有效信息付费
后期工作量	巨大，筛选过程极其痛苦	极小，几乎每张都是有效素材
最终成果质量	包含大量静止、无意义的“垃圾时间”	节奏紧凑，聚焦于“变化”的精华

显然，我需要的是后者。一个真正懂得“什么时候该出手，什么时候该摸鱼”的、充满智慧的——聪明的懒汉。

给摄像头装上“大脑”：懒惰是第一生产力

于是，我决定对我的摄影系统进行一次彻底的、颠覆性的“智能化”升级。这次，我没有教它如何更努力地工作，恰恰相反，我教给了它一门艺术——如何合理地“偷懒”。

它的核心工作原理，就像一位经验老道、洞察敏锐的情报官，他从不屑于上报那些“一切正常”的乏味报告，而只在“有情况”时才发出电报。

为了让它具备这种高级的判断力，我为它设计了三步走的“智慧流程”：

视觉的纯化：看见本质，而非表象

清晨的冷光和傍晚的暖光，会给同一场景染上截然不同的色调，但物体本身可能纹丝未动。因此，系统在比较前，会先把彩色画面和存档照片都转换为只有黑白灰的“素描模式”（灰度化）。

变化的度量：为“不同”赋予权重

系统将两张黑白照片进行像素级的叠加比对，生成“变化地图”，并计算其中亮色区域占比，得出变化率百分比，用于衡量“发生了什么”。

决断的艺术：设定一条智慧的“偷懒”基准

我为它设定了一个阈值，例如 0.5%。低于此值则跳过拍摄，只有当变化显著时才记录，节省资源、聚焦重要。

生活中的贴心管家：一个高度自律的系统

为了让它能 7x24 小时稳定运行，我设计了以下几套机制：

量身定制的“生物钟”

根据家庭节奏设定不同频率的检测：

晨光捕捉 (6-8点)：每 5 秒捕捉一次
日间活跃 (8-18点)：每 2 秒捕捉一次
黄昏慢品 (18-22点)：每 5 秒捕捉一次
午夜巡航 (22-6点)：每 10 秒捕捉一次

深谋远虑的“空间魔法”

当存储使用接近 85% 时，系统自动删除最旧的存档，确保运行空间始终充足。

百折不挠的“生存本能”

面对断电、摄像头失联等异常，系统具备重连重试机制，最大程度自愈保持在线。

意外的收获：成为生活的静谧观察者

系统的运行成果，远超预期，它让我发现：

微缩的家庭日晷

追踪阳光在家中地板上的路径变化，像一个巨大的光影时钟。

植物的无声舞蹈

延时视频中能看见多肉转动身体朝向太阳，充满生命的对话。

窗外的流动风景

记录窗外云卷云舒、雪后屋顶融化的水滴落下，一切如诗如画。

创造的乐趣，在于过程本身

从想法萌芽到系统成熟，这个从 0 到 1 的过程带给我的满足感是难以言喻的。

技术的魅力不在于它多复杂，而在于我们如何运用它去理解和体验生活。

如果你也对创造充满热情，那就从一个微小的点子开始吧。真正的门槛，从不在工具，而在你那份愿意“折腾”的初心。

开启你的创造之旅吧，去记录下属于你自己的、独一无二的时光故事。

项目代码：

import cv2
import numpy as np
import logging
import logging.handlers
import time
import os
import sys
import argparse
import signal
import shutil
import traceback
from datetime import datetime, time as dt_time
from threading import Event

# --- Script Information ---
SCRIPT_VERSION = "2.0.1"
SCRIPT_NAME = os.path.basename(__file__)

# --- Default Configuration ---
BASE_APP_DIR = "/opt/camera/"
LOG_DIR = os.path.join(BASE_APP_DIR, 'logs')
PID_FILE_PATH = f"/var/run/{SCRIPT_NAME.replace('.py', '.pid')}"
IMAGE_SAVE_BASE_DIR = "/opt/camera/captures"

LOG_LEVEL_CONFIG = "INFO"
LOG_FILE_NAME = "image_capture"
LOG_ROTATE_WHEN = "midnight"
LOG_ROTATE_INTERVAL = 1
LOG_ROTATE_BACKUP_COUNT = 30

DEFAULT_CAMERA_INDEX = 3
DEFAULT_CAMERA_DEVICE_PATH = "/dev/v4l/by-id/usb-Sonix_Technology_Co.__Ltd._UGREEN_Camera_2K_SN0001-video-index0"
DEFAULT_WIDTH = 1920
DEFAULT_HEIGHT = 1080
REQUESTED_FOURCC = 'YUYV'
JPEG_SAVE_QUALITY = 90

CAPTURE_SCHEDULE_CONFIG = [
    {"end_time_exclusive": dt_time(5, 0), "interval_seconds": 10},
    {"end_time_exclusive": dt_time(6, 0),  "interval_seconds": 5},
    {"end_time_exclusive": dt_time(21, 30),  "interval_seconds": 2.5},
    {"end_time_exclusive": dt_time(22, 30),  "interval_seconds": 5},
]
DEFAULT_INTERVAL_LATE_NIGHT = 10

PARAMETER_SET_RETRIES = 3
PARAMETER_SET_DELAY_SECONDS = 0.5
CAMERA_INIT_FAILURE_MAX_CONSECUTIVE = 5
CAMERA_INIT_RETRY_DELAY_SECONDS = 15
CAMERA_INIT_LONG_BACKOFF_SECONDS = 300

# MODIFICATION v2.0.1: New config for read failures
MAX_CONSECUTIVE_READ_FAILURES = 10 # Max consecutive cap.read() failures before longer pause
READ_FAILURE_LONG_BACKOFF_SECONDS = 60 # Longer pause after max read failures

FRAME_READ_ERROR_RETRY_DELAY_SECONDS = 5 # Short delay after a single read failure

# MODIFICATION v2.0.1: New config for imwrite failures
MAX_CONSECUTIVE_IMWRITE_FAILURES = 5 # Max consecutive cv2.imwrite() failures before shutdown

ENABLE_TIMESTAMP = True
TIMESTAMP_FORMAT = "%Y/%m/%d %H:%M:%S"

IMAGE_STORAGE_MONITOR_PATH = IMAGE_SAVE_BASE_DIR
IMAGE_STORAGE_MAX_USAGE_PERCENT = 85
IMAGE_STORAGE_CLEANUP_BATCH_DAYS = 1
DISK_CHECK_INTERVAL_SECONDS = 14400

# --- Global Variables ---
logger = None
shutdown_event = Event()
consecutive_imwrite_failures = 0 # MODIFICATION v2.0.1
consecutive_read_failures = 0    # MODIFICATION v2.0.1

# 默认的轮廓比较参数 (可以根据您的实际测试调整这些值)
DEFAULT_CONTOUR_PIXEL_THRESHOLD = 25   # 用于生成初始差异图的像素强度阈值
DEFAULT_CONTOUR_KERNEL_SIZE = (5, 5)   # 形态学膨胀操作的卷积核大小
DEFAULT_CONTOUR_DILATION_ITERATIONS = 2 # 膨胀操作的迭代次数
DEFAULT_CONTOUR_MIN_AREA_FILTER = 50.0 # 过滤掉小于此面积的差异轮廓

last_significant_frame = None
SIMILARITY_THRESHOLD_PERCENT_INT = 100 # 例如0.5%

# --- Logging Setup ---
# (setup_logging_system function from v2.0.0 is unchanged)
def setup_logging_system(log_dir, log_file_prefix, level_str, when, interval, backup_count):
    global logger
    numeric_level = getattr(logging, level_str.upper(), logging.INFO)

    if not os.path.exists(log_dir):
        try:
            os.makedirs(log_dir, exist_ok=True)
        except OSError as e:
            print(f"CRITICAL: Failed to create log directory {log_dir}: {e}", file=sys.stderr)
            sys.exit(1) 

    logger = logging.getLogger(SCRIPT_NAME)
    logger.setLevel(numeric_level)
    
    ## current_date_str = datetime.now().strftime("_%Y_%m_%d") # 例如：_2023_10_27
    ## current_date_str_new = datetime.now().strftime("%Y-%m-%d")
    ## actual_log_file_name = f"{log_file_prefix}.log.{current_date_str_new}"
    log_file_basename = f"{log_file_prefix}.log" # 例如 "image_capture.log"
    log_filepath = os.path.join(log_dir, log_file_basename) # 使用这个路径

    if logger.hasHandlers():
        logger.handlers.clear()

    formatter = logging.Formatter('%(asctime)s [%(levelname)-7s] [%(name)s:%(funcName)s:%(lineno)d] %(message)s')
    
    ## log_filepath = os.path.join(log_dir, actual_log_file_name)
    try:
        fh = logging.handlers.TimedRotatingFileHandler(
            log_filepath, when=when, interval=interval, backupCount=backup_count, encoding='utf-8'
        )
        fh.setLevel(numeric_level)
        fh.setFormatter(formatter)
        logger.addHandler(fh)
    except Exception as e:
        print(f"WARNING: Failed to initialize file logger at {log_filepath}: {e}", file=sys.stderr)

    ch = logging.StreamHandler(sys.stdout) 
    ch.setLevel(numeric_level) 
    ch.setFormatter(formatter)
    logger.addHandler(ch)
    
    logger.info(f"Logging initialized. Level: {level_str}. File: {log_filepath}")
    return logger

# --- PID File Management ---
# (create_pid_file, remove_pid_file functions from v2.0.0 are unchanged)
def create_pid_file():
    if not PID_FILE_PATH: return
    try:
        pid = os.getpid()
        os.makedirs(os.path.dirname(PID_FILE_PATH), exist_ok=True)
        with open(PID_FILE_PATH, 'w') as f:
            f.write(str(pid))
        logger.info(f"PID file created at {PID_FILE_PATH} with PID {pid}")
    except IOError as e:
        logger.error(f"Unable to create PID file {PID_FILE_PATH}: {e}")
        sys.exit(1)

def remove_pid_file():
    if not PID_FILE_PATH: return
    try:
        if os.path.exists(PID_FILE_PATH):
            os.remove(PID_FILE_PATH)
            logger.info(f"PID file {PID_FILE_PATH} removed.")
    except IOError as e:
        logger.warning(f"Unable to remove PID file {PID_FILE_PATH}: {e}")

# --- Signal Handling ---
def signal_term_handler(signum, frame):
    msg = f"接收到信号 {signal.Signals(signum).name} ({signum})，开始优雅停机..."
    if logger: logger.info(msg)
    else: print(msg, file=sys.stderr)
    shutdown_event.set()

# --- Core Camera and Image Processing Functions ---
# (get_fourcc_str, set_camera_parameter, initialize_camera, add_timestamp_to_frame
#  from v2.0.0 are good, ensure logger is used, and set_camera_parameter uses shutdown_event.wait)
def get_fourcc_str(fourcc_int: int) -> str: # Identical to v2.0.0
    if fourcc_int == 0: return "N/A (0)"
    try:
        return "".join([chr((fourcc_int >> 8 * i) & 0xFF) for i in range(4)]).strip()
    except Exception as e:
        logger.warning(f"转换FOURCC整数 {hex(fourcc_int)} 到字符串失败: {e}")
        return f"Unknown ({hex(fourcc_int)})"

def set_camera_parameter(cap: cv2.VideoCapture, prop_id: int, value, param_name: str, 
                         retries: int = PARAMETER_SET_RETRIES, delay: float = PARAMETER_SET_DELAY_SECONDS) -> bool: # Identical to v2.0.0
    logger.info(f"尝试设置摄像头参数 {param_name} 为 {value}")
    for i in range(retries):
        cap.set(prop_id, value)
        if shutdown_event.wait(timeout=delay): return False # Shutdown requested

        actual_value = cap.get(prop_id)
        is_set = False
        requested_value_for_log = value
        actual_value_for_log = actual_value

        if prop_id == cv2.CAP_PROP_FOURCC:
            target_int = int(value) 
            actual_int = int(actual_value)
            is_set = (actual_int == target_int)
            requested_value_for_log = get_fourcc_str(target_int)
            actual_value_for_log = get_fourcc_str(actual_int)
        elif isinstance(value, float):
            is_set = (abs(float(actual_value) - value) < 1e-9) 
        else: 
            is_set = (int(actual_value) == int(value))
        
        logger.debug(f"尝试 {i+1}/{retries} 设置 {param_name}: 请求 {requested_value_for_log}, 实际 {actual_value_for_log}")
        if is_set:
            logger.info(f"参数 {param_name} 成功设置为 {requested_value_for_log}")
            return True
        time.sleep(0.1)
            
    final_actual_value = cap.get(prop_id)
    if prop_id == cv2.CAP_PROP_FOURCC: final_actual_value = get_fourcc_str(int(final_actual_value))
    logger.warning(f"无法将参数 {param_name} 设置为 {requested_value_for_log} "
                   f"经过 {retries} 次尝试后，实际值为 {final_actual_value}")
    return False

def initialize_camera(camera_path: str, width: int, height: int, req_fourcc_str: str): # Identical to v2.0.0
    logger.info(f"尝试打开并初始化设备 {camera_path} (使用 V4L2 后端)")
    
    device_path = camera_path
    if not os.path.exists(device_path):
        logger.error(f"摄像头设备节点 {device_path} 不存在。")
        return None, "NODE_NOT_FOUND"

    cap = cv2.VideoCapture(camera_path, cv2.CAP_V4L2)

    if not cap.isOpened():
        logger.error(f"无法打开摄像头 {camera_path}")
        return None, "OPEN_FAILED"

    effective_fourcc = "NOT_SET"
    if req_fourcc_str:
        target_fourcc_int = cv2.VideoWriter_fourcc(*req_fourcc_str)
        set_camera_parameter(cap, cv2.CAP_PROP_FOURCC, target_fourcc_int, "FOURCC")
    
    set_camera_parameter(cap, cv2.CAP_PROP_FPS, 10, "FPS")

    if shutdown_event.is_set(): cap.release(); return None, "SHUTDOWN_DURING_INIT"
    time.sleep(0.1) 
    current_fourcc_int = int(cap.get(cv2.CAP_PROP_FOURCC))
    effective_fourcc = get_fourcc_str(current_fourcc_int)
    if req_fourcc_str and effective_fourcc.upper() != req_fourcc_str.upper():
         logger.warning(f"请求的FOURCC {req_fourcc_str} 未能精确设置，摄像头实际为 {effective_fourcc}")

    set_camera_parameter(cap, cv2.CAP_PROP_FRAME_WIDTH, width, "Width")
    if shutdown_event.is_set(): cap.release(); return None, "SHUTDOWN_DURING_INIT"
    set_camera_parameter(cap, cv2.CAP_PROP_FRAME_HEIGHT, height, "Height")
    if shutdown_event.is_set(): cap.release(); return None, "SHUTDOWN_DURING_INIT"
    
    time.sleep(0.2) 
    actual_width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
    actual_height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
    actual_fps_val = cap.get(cv2.CAP_PROP_FPS) 
    current_fourcc_int = int(cap.get(cv2.CAP_PROP_FOURCC)) 
    effective_fourcc = get_fourcc_str(current_fourcc_int)

    logger.info(f"摄像头 {camera_path} 初始化完成。")
    logger.info(f"  请求参数 -> FOURCC: {req_fourcc_str if req_fourcc_str else 'N/A'}, 尺寸: {width}x{height}")
    logger.info(f"  实际参数 -> FOURCC: {effective_fourcc} ({hex(current_fourcc_int)}), "
                f"尺寸: {actual_width}x{actual_height}, "
                f"报告FPS: {actual_fps_val:.2f}")
    
    if actual_width != width or actual_height != height:
        logger.error(f"摄像头实际分辨率 {actual_width}x{actual_height} 与请求的 {width}x{height} 不符！")
    
    return cap, effective_fourcc

def add_timestamp_to_frame(frame_to_modify, timestamp_format_str): # Identical to v2.0.0
    if not ENABLE_TIMESTAMP:
        return frame_to_modify
    timestamp_text = datetime.now().strftime(timestamp_format_str)
    font = cv2.FONT_HERSHEY_SIMPLEX
    img_h, img_w = frame_to_modify.shape[:2]
    font_scale = (img_h / 1080.0) * 1.0
    if font_scale < 0.5: font_scale = 0.5
    thickness = max(1, int(font_scale * 2.0)) 
    margin = max(10, int(img_h * 0.05)) 

    text_size, baseline = cv2.getTextSize(timestamp_text, font, font_scale, thickness)
    text_width, text_height = text_size
    org_x = img_w - text_width - margin
    org_y = img_h - margin 
    
    cv2.putText(frame_to_modify, timestamp_text, (org_x, org_y), font, font_scale, 
                (255, 255, 255), thickness, cv2.LINE_AA, bottomLeftOrigin=False)
    return frame_to_modify

def are_frames_similar(frame1: np.ndarray | None,
                       frame2: np.ndarray | None,
                       similarity_diff_rate_threshold_int: int) -> bool:
    """
    比较两个帧的相似度，基于轮廓面积差异率。
    帧的顺序无关。

    参数:
        frame1: 第一个帧 (NumPy array) 或 None。
        frame2: 第二个帧 (NumPy array) 或 None。
        similarity_diff_rate_threshold_int (int): 相似度百分比阈值。
            这是一个整数，例如 50 代表差异率上限为 0.50%。
            如果实际差异率 <= 此阈值对应的百分比，则认为帧相似。

    返回:
        bool:
            - 如果任一帧无法解析为有效图像 (例如 None 或类型不对)，返回 False (不相似/无法比较)。
            - 如果轮廓面积差异率 <= (similarity_diff_rate_threshold_int / 100.0)%，返回 True (相似/变化小)。
            - 否则 (差异率较大)，返回 False (不相似/变化大)。
    """

    # 1. 检查输入帧的有效性
    # cap.read() 返回的 ret, frame。如果 ret 是 False，frame可能是 None 或无效数据
    if not isinstance(frame1, np.ndarray) or frame1.size == 0:
        logger.debug("are_frames_similar: frame1 无效 (非 NumPy 数组、None 或空数组)。返回 False。")
        return False
    if not isinstance(frame2, np.ndarray) or frame2.size == 0:
        logger.debug("are_frames_similar: frame2 无效 (非 NumPy 数组、None 或空数组)。返回 False。")
        return False

    # 2. 确保图像尺寸相同 (将 frame2 调整为 frame1 的尺寸)
    h1, w1 = frame1.shape[:2]
    h2, w2 = frame2.shape[:2]
    frame2_resized = frame2

    if (h1, w1) != (h2, w2):
        return False
        logger.debug(f"are_frames_similar: 帧尺寸不同。将 frame2 从 ({w2}x{h2}) 调整为 ({w1}x{h1})。")
        try:
            frame2_resized = cv2.resize(frame2, (w1, h1), interpolation=cv2.INTER_AREA)
        except cv2.error as e:
            logger.error(f"are_frames_similar: 调整 frame2 尺寸失败: {e}。返回 False。")
            return False # 调整尺寸失败，无法比较

    # 3. 转换为灰度图进行比较
    #    确保处理单通道和三通道输入，最终得到单通道灰度图
    try:
        if frame1.ndim == 3 and frame1.shape[2] == 3: # BGR
            gray1 = cv2.cvtColor(frame1, cv2.COLOR_BGR2GRAY)
        elif frame1.ndim == 2: # Already grayscale
            gray1 = frame1
        else:
            logger.warning(f"are_frames_similar: frame1 格式未知 (shape: {frame1.shape})。返回 False。")
            return False

        if frame2_resized.ndim == 3 and frame2_resized.shape[2] == 3: # BGR
            gray2 = cv2.cvtColor(frame2_resized, cv2.COLOR_BGR2GRAY)
        elif frame2_resized.ndim == 2: # Already grayscale
            gray2 = frame2_resized
        else:
            logger.warning(f"are_frames_similar: frame2_resized 格式未知 (shape: {frame2_resized.shape})。返回 False。")
            return False
    except cv2.error as e:
        logger.error(f"are_frames_similar: 转换为灰度图失败: {e}。返回 False。")
        return False

    # 4. 计算轮廓面积差异率
    image_total_pixels = gray1.shape[0] * gray1.shape[1]
    if image_total_pixels == 0:
        logger.debug("are_frames_similar: 图像总像素为0。返回 False。")
        return False

    abs_diff_img = cv2.absdiff(gray1, gray2)
    _, thresh_img = cv2.threshold(abs_diff_img,
                                  DEFAULT_CONTOUR_PIXEL_THRESHOLD,
                                  255,
                                  cv2.THRESH_BINARY)

    kernel = np.ones(DEFAULT_CONTOUR_KERNEL_SIZE, np.uint8)
    dilated_thresh_img = cv2.dilate(thresh_img,
                                    kernel,
                                    iterations=DEFAULT_CONTOUR_DILATION_ITERATIONS)

    contours, _ = cv2.findContours(dilated_thresh_img,
                                   cv2.RETR_EXTERNAL,
                                   cv2.CHAIN_APPROX_SIMPLE)

    total_significant_contour_area = 0.0
    for contour in contours:
        current_contour_area = cv2.contourArea(contour)
        if current_contour_area > DEFAULT_CONTOUR_MIN_AREA_FILTER:
            total_significant_contour_area += current_contour_area

    contour_area_actual_diff_rate_percent = (total_significant_contour_area / image_total_pixels) * 100.0

    # 5. 根据阈值判断是否相似
    # 将传入的整数阈值转换为实际百分比上限
    similarity_threshold_as_percentage = similarity_diff_rate_threshold_int / 100.0

    logger.debug(f"are_frames_similar: 实际轮廓差异率: {contour_area_actual_diff_rate_percent:.4f}%, " +
                 f"设定的相似度差异上限: {similarity_threshold_as_percentage:.4f}% " +
                 f"(传入整数: {similarity_diff_rate_threshold_int})")

    if contour_area_actual_diff_rate_percent <= similarity_threshold_as_percentage:
        # 差异小或等于阈值，认为相似 (变化小)
        # logger.info(f"are_frames_similar: 差异率达标{contour_area_actual_diff_rate_percent:.4f}%，判定为相似 (True)。")
        return True
    else:
        # 差异大，认为不相似 (变化大)
        # logger.info(f"are_frames_similar: 差异率超标{contour_area_actual_diff_rate_percent:.4f}%，判定为不相似 (False)。")
        return False

def process_and_save_frame(frame_data, effective_fourcc, base_save_dir, jpeg_quality_val, ts_format): # Identical to v2.0.0
    global consecutive_imwrite_failures # MODIFICATION v2.0.1
    global last_significant_frame

    if frame_data is None:
        logger.error("接收到空帧，无法处理。")
        return None

    logger.debug(f"接收到帧。原始 - 尺寸: {frame_data.shape}, dtype: {frame_data.dtype}, FOURCC上下文: {effective_fourcc}")
    processed_frame = frame_data

    # try:
    #    target_size = (1920, 1080)
    #    if frame_data.shape[1] != target_size[0] or frame_data.shape[0] != target_size[1]:
    #        processed_frame = cv2.resize(frame_data, target_size, interpolation=cv2.INTER_LANCZOS4)
    #        logger.info(f"图像缩放完成（高精度），目标尺寸: {target_size}")
    #except Exception as e:
    #    logger.error(f"图像缩放失败: {e}", exc_info=True)

    if effective_fourcc.upper() in ['YUYV', 'YUY2'] and \
       not (processed_frame.ndim == 3 and processed_frame.shape[2] == 3):
        logger.info(f"帧的FOURCC上下文为 {effective_fourcc} 且非BGR，尝试YUV->BGR转换。帧Shape: {processed_frame.shape}")
        try:
            if processed_frame.shape[1] == DEFAULT_WIDTH * 2 and processed_frame.ndim == 2: 
                 processed_frame = cv2.cvtColor(processed_frame, cv2.COLOR_YUV2BGR_YUYV) 
            elif processed_frame.ndim == 3 and processed_frame.shape[2] == 2: 
                 processed_frame = cv2.cvtColor(processed_frame, cv2.COLOR_YUV2BGR_YUYV)
            else:
                logger.warning(f"未知的YUYV帧结构: {processed_frame.shape}，无法自动转换。")
            
            if processed_frame.ndim == 3 and processed_frame.shape[2] == 3:
                 logger.info(f"YUV 转换为 BGR 成功. 新图像尺寸: {processed_frame.shape}")
            else: 
                 logger.error(f"YUV 转换为 BGR 后尺寸/通道数不正确: {processed_frame.shape}. 保留原始帧。")
                 processed_frame = frame_data 
        except cv2.error as e:
            logger.error(f"YUV 转换为 BGR 失败: {e}. 将使用原始帧。", exc_info=True)
            processed_frame = frame_data
    elif processed_frame.ndim == 2: 
        logger.info(f"图像是单通道灰度图 (shape: {processed_frame.shape})，转换为BGR。")
        processed_frame = cv2.cvtColor(processed_frame, cv2.COLOR_GRAY2BGR)
    elif not (processed_frame.ndim == 3 and processed_frame.shape[2] == 3):
        logger.warning(f"图像格式未知或非预期 (shape: {processed_frame.shape}). 尝试直接处理。")

    # 判断是否接近，如果和上一次成功保存类似则直接跳过
    frames_are_indeed_similar = are_frames_similar(
        last_significant_frame,
        processed_frame,
        SIMILARITY_THRESHOLD_PERCENT_INT
    )
    if frames_are_indeed_similar:
        #if logger: # logger.info(f"当前帧与上一显著帧相似 (差异 <= {SIMILARITY_THRESHOLD_PERCENT_INT/100.0:.2f}%)，不保存。")
        perform_save_this_frame = False
        return "SIMILARITY"
    else:
        # if logger: logger.info(f"当前帧与上一显著帧不相似 (差异 > {SIMILARITY_THRESHOLD_PERCENT_INT/100.0:.2f}%)，将保存。")
        perform_save_this_frame = True
        last_significant_frame = processed_frame

    try:
        frame_with_timestamp = add_timestamp_to_frame(processed_frame.copy(), ts_format)
    except Exception as e:
        logger.error(f"添加时间戳失败: {e}. 将保存不带时间戳的图像。", exc_info=True)
        frame_with_timestamp = processed_frame

    now = datetime.now()
    save_subdir = os.path.join(base_save_dir, now.strftime("%Y-%m"), now.strftime("%d"))
    
    try:
        os.makedirs(save_subdir, exist_ok=True) 
    except OSError as e:
        logger.error(f"创建目录 {save_subdir} 失败: {e}. 无法保存图像。")
        consecutive_imwrite_failures +=1 # MODIFICATION v2.0.1
        return None

    #time_str = now.strftime("%H%M%S_%f") 
    #filename = f"{time_str}.jpg" 
    #filepath = os.path.join(save_subdir, filename)
    file_timestamp = now.strftime("%Y%m%d_%H%M%S_%f")
    filename = f"capture_{file_timestamp}.jpg"
    filepath = os.path.join(save_subdir, filename) # 保存到年月子目录中

    logger.debug(f"尝试将图像保存到: {filepath} (质量: {jpeg_quality_val})")
    try:
        save_success = cv2.imwrite(filepath, frame_with_timestamp, [cv2.IMWRITE_JPEG_QUALITY, jpeg_quality_val])
        if save_success:
            logger.debug(f"图像成功保存为JPEG: {filepath}")
            consecutive_imwrite_failures = 0 # MODIFICATION v2.0.1: Reset on success
            try:
                os.chmod(filepath, 0o644) 
                logger.debug(f"文件权限设置为 644: {filepath}")
            except OSError as e:
                logger.warning(f"设置文件 {filepath} 权限失败: {e}")
            return filepath
        else:
            logger.error(f"cv2.imwrite 保存JPEG图像失败 (返回False): {filepath}")
            consecutive_imwrite_failures +=1 # MODIFICATION v2.0.1
            return None
    except Exception as e:
        logger.error(f"cv2.imwrite 保存图像时发生异常: {e}", exc_info=True)
        consecutive_imwrite_failures +=1 # MODIFICATION v2.0.1
        return None

# --- Disk Space Management ---
def get_oldest_day_dir(base_dir: str) -> str | None: # Identical to v2.0.0
    all_day_paths = []
    if not os.path.isdir(base_dir):
        logger.warning(f"get_oldest_day_dir: Base directory '{base_dir}' not found or not a directory.")
        return None
    for ym_dir_name in sorted(os.listdir(base_dir)):
        ym_path = os.path.join(base_dir, ym_dir_name)
        if os.path.isdir(ym_path) and len(ym_dir_name) == 7 and ym_dir_name[4] == '-': # Valid YYYY-MM
            for d_dir_name in sorted(os.listdir(ym_path)):
                d_path = os.path.join(ym_path, d_dir_name)
                if os.path.isdir(d_path) and len(d_dir_name) == 2: # Valid DD
                    try: # Ensure DD is integer, further validating format
                        int(d_dir_name) 
                        all_day_paths.append(d_path)
                    except ValueError:
                        logger.debug(f"Skipping non-day directory: {d_path}")
                        continue
    if all_day_paths:
        return all_day_paths[0] # Lexicographical sort of YYYY-MM/DD is chronological
    return None

def check_and_manage_disk_space(): # Identical to v2.0.0 logic
    try:
        usage = shutil.disk_usage(IMAGE_STORAGE_MONITOR_PATH)
        percent_used = (usage.used / usage.total) * 100
        logger.info(f"磁盘空间监控: {IMAGE_STORAGE_MONITOR_PATH} - Total: {usage.total // (1024**3)}GB, "
                    f"Used: {usage.used // (1024**3)}GB ({percent_used:.1f}%), "
                    f"Free: {usage.free // (1024**3)}GB")

        if percent_used > IMAGE_STORAGE_MAX_USAGE_PERCENT:
            logger.warning(f"磁盘使用率 ({percent_used:.1f}%) 已超过阈值 ({IMAGE_STORAGE_MAX_USAGE_PERCENT}%). "
                           f"尝试清理 {IMAGE_STORAGE_CLEANUP_BATCH_DAYS} 个最旧的日期目录...")
            
            for i in range(IMAGE_STORAGE_CLEANUP_BATCH_DAYS):
                if shutdown_event.is_set(): 
                    logger.info("Shutdown requested during disk cleanup.")
                    break 
                
                oldest_dir_to_delete = get_oldest_day_dir(IMAGE_SAVE_BASE_DIR)
                if oldest_dir_to_delete:
                    logger.warning(f"准备删除最旧的日期目录 ({i+1}/{IMAGE_STORAGE_CLEANUP_BATCH_DAYS}): {oldest_dir_to_delete}")
                    try:
                        shutil.rmtree(oldest_dir_to_delete)
                        logger.info(f"已成功删除目录: {oldest_dir_to_delete}")
                    except OSError as e:
                        logger.error(f"删除目录 {oldest_dir_to_delete} 失败: {e}", exc_info=True)
                        break 
                else:
                    logger.warning("没有找到可以删除的旧日期目录。")
                    break 
    except FileNotFoundError:
        logger.error(f"磁盘空间监控路径 {IMAGE_STORAGE_MONITOR_PATH} 未找到。")
    except Exception as e:
        logger.error(f"检查或管理磁盘空间时发生错误: {e}", exc_info=True)

# --- Get Current Capture Interval ---
def get_current_capture_interval() -> int: # Identical to v2.0.0
    now_time = datetime.now().time()
    for schedule_item in CAPTURE_SCHEDULE_CONFIG:
        if now_time < schedule_item["end_time_exclusive"]:
            return schedule_item["interval_seconds"]
    return DEFAULT_INTERVAL_LATE_NIGHT

# --- Main Service Logic ---
def run_capture_service():
    global shutdown_event, cap, effective_fourcc # cap and effective_fourcc might be better as instance vars if this were a class
    global consecutive_imwrite_failures, consecutive_read_failures # MODIFICATION v2.0.1
    global last_significant_frame
    last_significant_frame = None # 确保服务启动时重置

    cap = None # Ensure cap is defined in this scope
    effective_fourcc = "NOT_SET_INITIALLY"
    init_failures = 0
    last_disk_check_time = 0
    consecutive_imwrite_failures = 0 # Reset counters at service start
    consecutive_read_failures = 0

    logger.debug(f"图像捕获服务主逻辑启动。")
    # ... (logging of schedule, camera target etc. from v2.0.0)
    logger.info(f"  时间表: " + ", ".join([f"<{s['end_time_exclusive'].strftime('%H:%M')} ({s['interval_seconds']}s)" for s in CAPTURE_SCHEDULE_CONFIG]) + 
                f", >=22:00 ({DEFAULT_INTERVAL_LATE_NIGHT}s)")
    logger.info(f"  目标摄像头: {DEFAULT_CAMERA_DEVICE_PATH}")
    logger.info(f"  摄像头参数：{DEFAULT_WIDTH}x{DEFAULT_HEIGHT}, FOURCC: {REQUESTED_FOURCC}")
    logger.info(f"  图片保存至: {IMAGE_SAVE_BASE_DIR} (JPEG质量: {JPEG_SAVE_QUALITY})")
    logger.info(f"  磁盘监控: 路径 '{IMAGE_STORAGE_MONITOR_PATH}', 阈值 {IMAGE_STORAGE_MAX_USAGE_PERCENT}%")


    last_capture_time = time.monotonic() 

    while not shutdown_event.is_set():
        current_interval = get_current_capture_interval()
        try:
            current_monotonic_time = time.monotonic()
            if current_monotonic_time - last_disk_check_time > DISK_CHECK_INTERVAL_SECONDS:
                check_and_manage_disk_space()
                last_disk_check_time = current_monotonic_time

            if cap is None or not cap.isOpened():
                logger.info("摄像头未连接或需要重新初始化...")
                if cap: cap.release() 
                
                cap, effective_fourcc = initialize_camera(
                    DEFAULT_CAMERA_DEVICE_PATH, DEFAULT_WIDTH, DEFAULT_HEIGHT, REQUESTED_FOURCC
                )
                if not cap:
                    init_failures += 1
                    logger.error(f"摄像头初始化失败 (连续第 {init_failures} 次)。")
                    if init_failures >= CAMERA_INIT_FAILURE_MAX_CONSECUTIVE:
                        logger.critical(f"已连续 {init_failures} 次无法初始化摄像头。将等待较长时间 ({CAMERA_INIT_LONG_BACKOFF_SECONDS}s) 后重试。")
                        shutdown_event.wait(CAMERA_INIT_LONG_BACKOFF_SECONDS)
                        init_failures = 0 
                    else:
                        shutdown_event.wait(CAMERA_INIT_RETRY_DELAY_SECONDS)
                    continue 
                
                init_failures = 0 
                last_capture_time = time.monotonic() 
                consecutive_read_failures = 0 # Reset read failure counter on successful init

            elapsed_since_last_capture = time.monotonic() - last_capture_time
            wait_time = current_interval - elapsed_since_last_capture

            if wait_time > 0:
                # logger.info(f"当前时间: {datetime.now().strftime('%H:%M:%S')}, 间隔: {current_interval}s. 还需 {wait_time:.2f} 秒...")
                shutdown_event.wait(timeout=wait_time) 
                if shutdown_event.is_set(): break 
            
            if shutdown_event.is_set(): break 

            last_capture_time = time.monotonic() 
            logger.debug(f"尝试捕获图像帧 (当前间隔: {current_interval}s)...")

            for _ in range(4):
                # 清空缓冲帧
                cap.grab();
            ret, frame = cap.read()

            if not ret or frame is None:
                logger.error("无法从摄像头获取图像帧。摄像头可能已断开连接或出现问题。")
                consecutive_read_failures += 1 # MODIFICATION v2.0.1
                logger.info(f"连续读帧失败次数: {consecutive_read_failures}")
                if cap: cap.release()
                cap = None 
                
                if consecutive_read_failures >= MAX_CONSECUTIVE_READ_FAILURES:
                    logger.critical(f"已连续 {consecutive_read_failures} 次无法读取帧。将等待较长时间 ({READ_FAILURE_LONG_BACKOFF_SECONDS}s) 后尝试重连。")
                    shutdown_event.wait(READ_FAILURE_LONG_BACKOFF_SECONDS)
                    consecutive_read_failures = 0 # Reset after long backoff
                else:
                    shutdown_event.wait(FRAME_READ_ERROR_RETRY_DELAY_SECONDS) 
                continue
            
            consecutive_read_failures = 0 # Reset on successful read MODIFICATION v2.0.1

            saved_filepath = process_and_save_frame(
                frame, effective_fourcc, IMAGE_SAVE_BASE_DIR, 
                JPEG_SAVE_QUALITY, TIMESTAMP_FORMAT
            )
            if saved_filepath == "SIMILARITY":
                logger.debug("图像接近，跳过保存")
            elif isinstance(saved_filepath, str) and saved_filepath.lower().endswith(".jpg"):
                logger.debug(f"图像捕获并成功保存: {saved_filepath}")
                # consecutive_imwrite_failures is reset inside process_and_save_frame
            else:
                logger.warning("本次图像捕获未能成功保存。")
                # consecutive_imwrite_failures is incremented inside process_and_save_frame
                if consecutive_imwrite_failures >= MAX_CONSECUTIVE_IMWRITE_FAILURES:
                    logger.critical(f"已连续 {consecutive_imwrite_failures} 次无法保存图像到磁盘。服务将停止。")
                    shutdown_event.set() # Signal shutdown
                    break # Exit while loop

        except cv2.error as e: 
            logger.error(f"主循环中发生 OpenCV 特定错误: {e}", exc_info=True)
            if cap: cap.release()
            cap = None
            logger.info(f"因 OpenCV 错误，将等待 {CAMERA_INIT_RETRY_DELAY_SECONDS}s 后尝试重启摄像头。")
            shutdown_event.wait(CAMERA_INIT_RETRY_DELAY_SECONDS)
        except Exception as e: 
            logger.critical(f"主循环中发生未预料的严重错误: {e}", exc_info=True)
            if cap: cap.release() 
            cap = None
            logger.info(f"因严重错误，将等待 {CAMERA_INIT_LONG_BACKOFF_SECONDS}s 后尝试重启摄像头。")
            shutdown_event.wait(CAMERA_INIT_LONG_BACKOFF_SECONDS)
            # Consider uncommenting 'raise' for systemd to handle restart on truly unrecoverable errors
            # raise

    # Loop exited (likely due to shutdown_event)
    if cap and cap.isOpened():
        logger.info("正在释放摄像头资源...")
        cap.release()
    logger.info("图像捕获服务主逻辑已停止。")


# --- Main Application Entry Point & CLI Argument Parsing ---
def main():
    global logger, PID_FILE_PATH # Allow modification if args change them

    parser = argparse.ArgumentParser(description=f"{SCRIPT_NAME} - Image Capture Service (v{SCRIPT_VERSION})")
    parser.add_argument('action', nargs='?', choices=['start', 'stop', 'status', 'foreground'], 
                        default='foreground', 
                        help="Action: start (daemonize - for traditional init), stop, status, or foreground (default, for systemd/debug).")
    parser.add_argument('--pidfile', default=PID_FILE_PATH, 
                        help=f"Path to PID file (default: {PID_FILE_PATH})")
    parser.add_argument('--logdir', default=LOG_DIR, help=f"Path to log directory (default: {LOG_DIR})")
    parser.add_argument('--loglevel', default=LOG_LEVEL_CONFIG, choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'],
                        help=f"Logging level (default: {LOG_LEVEL_CONFIG})")
    # For true daemonization with python-daemon, more args like --user, --group, --working-directory would be needed.
    # For now, 'start' is conceptual if not using systemd or a proper daemon library.

    args = parser.parse_args()
    
    PID_FILE_PATH = os.path.abspath(args.pidfile)
    # Initialize logging system (now that PID_FILE_PATH for potential log inside pid dir is known)
    try:
        os.makedirs(args.logdir, exist_ok=True)
        # Also ensure image save base dir exists before service starts trying to write into it.
        if not os.path.exists(IMAGE_SAVE_BASE_DIR): # This check should ideally use an absolute path too
            os.makedirs(IMAGE_SAVE_BASE_DIR, exist_ok=True)
    except OSError as e:
        # If using print before logger is initialized
        print(f"CRITICAL: Failed to create essential directories (Log dir: {args.logdir} or Image Base: {IMAGE_SAVE_BASE_DIR}): {e}", file=sys.stderr)
        sys.exit(1)
    logger = setup_logging_system(args.logdir, LOG_FILE_NAME, args.loglevel.upper(), 
                                  LOG_ROTATE_WHEN, LOG_ROTATE_INTERVAL, LOG_ROTATE_BACKUP_COUNT)

    # Handle actions
    if args.action == 'start' or args.action == 'foreground':
        if args.action == 'start': # For 'start', implies daemonization is desired if not under systemd
            logger.info("Action 'start': Daemonization not yet fully implemented in this script for non-systemd. Running in foreground.")
            logger.info("For systemd, use Type=simple and run script directly (which defaults to foreground).")
            # If using python-daemon, daemonization context would be entered here.
            # For now, 'start' and 'foreground' behave similarly.
        
        logger.info(f"Starting {SCRIPT_NAME} v{SCRIPT_VERSION} in foreground mode...")
        
        # Check PID file before creating a new one
        if os.path.exists(PID_FILE_PATH):
            try:
                with open(PID_FILE_PATH, 'r') as f_pid_check:
                    existing_pid = int(f_pid_check.read().strip())
                os.kill(existing_pid, 0) # Check if process with this PID is running
                logger.warning(f"Service already running with PID {existing_pid} (found in {PID_FILE_PATH}). If this is wrong, remove PID file and restart.")
                sys.exit(1) 
            except (IOError, ValueError, ProcessLookupError): 
                logger.warning(f"Found stale PID file {PID_FILE_PATH}. Removing it.")
                try: os.remove(PID_FILE_PATH)
                except OSError as e_rm: logger.error(f"Error removing stale PID file {PID_FILE_PATH}: {e_rm}")
        
        create_pid_file()
        signal.signal(signal.SIGTERM, signal_term_handler)
        signal.signal(signal.SIGINT, signal_term_handler) 

        try:
            run_capture_service() 
        except Exception as e: 
            logger.critical(f"Unhandled exception in run_capture_service: {e}", exc_info=True)
            logger.critical(traceback.format_exc()) # Ensure full traceback is logged
            sys.exit(1) 
        finally:
            remove_pid_file() 
            logger.info(f"{SCRIPT_NAME} has shut down.")
            logging.shutdown() 
        sys.exit(0) 

    elif args.action == 'stop':
        logger.info("Action: stop")
        if not os.path.exists(PID_FILE_PATH):
            logger.warning(f"PID file {PID_FILE_PATH} not found. Service may not be running.")
            sys.exit(1) # Changed to 1 as "not running" is often a failure for "stop"
        try:
            with open(PID_FILE_PATH, 'r') as f:
                pid = int(f.read().strip())
        except (IOError, ValueError) as e:
            logger.error(f"Invalid PID file {PID_FILE_PATH}: {e}. Remove it manually if service is stuck.")
            sys.exit(1)

        try:
            logger.info(f"Sending SIGTERM to process {pid}...")
            os.kill(pid, signal.SIGTERM)

            terminated_successfully = False
            logger.info(f"Waiting up to 10 seconds for process {pid} to terminate...")
            for i in range(10): # Wait up to 10 seconds
                time.sleep(1) # 等待1秒
                try:
                    os.kill(pid, 0) # 检查进程是否仍然存在
                    logger.debug(f"Process {pid} is still alive (attempt {i+1}/10).")
                except ProcessLookupError:
                    logger.info(f"Process {pid} terminated successfully within {i+1} second(s).")
                    terminated_successfully = True
                    break # 进程已终止，退出等待循环
                except Exception as e_check: # 其他检查时发生的错误
                    logger.error(f"Error checking status for PID {pid}: {e_check}")
                    # 发生错误，可能无法确认状态，也退出循环
                    break 

            if not terminated_successfully:
                # 如果10秒后循环正常结束，但进程未被确认终止（通常意味着os.kill(pid,0)没报错）
                logger.error(f"Process {pid} did not terminate after 10 seconds. Consider manual check or SIGKILL.")
                # 您原始代码中在这之后还有一个try/except ProcessLookupError来做最后确认，
                # 如果这里的逻辑是，即使循环完了，还想再确认一次，是可以保留的。
                # 但如果上面的循环因为ProcessLookupError退出了，terminated_successfully会是true。

        except ProcessLookupError: # 这个捕获的是 os.kill(pid, signal.SIGTERM) 时，进程就已经不存在的情况
            logger.info(f"Process {pid} was already terminated or PID was invalid when SIGTERM was attempted.")
        except PermissionError:
            logger.error(f"No permission to send signal to process {pid}. Are you root?")
            sys.exit(1)
        except Exception as e:
            logger.error(f"Error stopping service: {e}", exc_info=True)
            sys.exit(1)
        finally:
            if terminated_successfully and os.path.exists(PID_FILE_PATH):
                # 服务进程已被此 'stop' 命令确认终止，
                # 但其 PID 文件仍然存在（服务可能未能自行删除）。
                # 可以安全地将其作为陈旧 PID 文件移除。
                logger.warning(f"Process {pid} terminated, but its PID file {PID_FILE_PATH} still exists. Removing stale PID file.")
                remove_pid_file()
            elif not terminated_successfully and os.path.exists(PID_FILE_PATH):
                # 服务进程未被此 'stop' 命令确认终止，且 PID 文件仍然存在。
                # 此时不应自动删除 PID 文件，因为它可能仍然代表一个正在运行（但可能卡住）的进程。
                logger.warning(f"Process {pid} may still be running after stop attempt. PID file {PID_FILE_PATH} will not be removed by this 'stop' action.")
                # 如果 os.path.exists(PID_FILE_PATH) 为 False，说明PID文件已经被服务进程自己清掉了，或者一开始就没有，这里不需要额外操作。
    elif args.action == 'status':
        logger.info("Action: status")
        if not os.path.exists(PID_FILE_PATH):
            print(f"{SCRIPT_NAME} is not running (no PID file).")
            logger.info(f"{SCRIPT_NAME} is not running (no PID file).")
            sys.exit(3) 
        try:
            with open(PID_FILE_PATH, 'r') as f:
                pid = int(f.read().strip())
        except (IOError, ValueError):
            print(f"{SCRIPT_NAME} status unknown (invalid PID file: {PID_FILE_PATH}).")
            logger.warning(f"Invalid PID file: {PID_FILE_PATH}")
            sys.exit(4) 
        
        try:
            os.kill(pid, 0) 
            print(f"{SCRIPT_NAME} is running with PID {pid}.")
            logger.info(f"{SCRIPT_NAME} is running with PID {pid}.")
            sys.exit(0) 
        except ProcessLookupError:
            print(f"{SCRIPT_NAME} is not running (PID {pid} from stale PID file {PID_FILE_PATH} not found).")
            logger.warning(f"Stale PID file: process {pid} not found. Removing PID file.")
            remove_pid_file()
            sys.exit(3) 
        except PermissionError:
            print(f"{SCRIPT_NAME} with PID {pid} seems to be running, but no permission to check fully.")
            logger.warning(f"Running with PID {pid}, but no permission to check fully.")
            sys.exit(4) 
        except Exception as e:
            print(f"Error checking status for PID {pid}: {e}")
            logger.error(f"Error checking status for PID {pid}: {e}", exc_info=True)
            sys.exit(4) 

if __name__ == "__main__":
    # Basic signal handling for the main entry point itself, before run_capture_service sets its own
    signal.signal(signal.SIGTERM, signal_term_handler) 
    signal.signal(signal.SIGINT, signal_term_handler) 
    try:
        main()
    except SystemExit as e:
        # sys.exit() was called, possibly by argparse or our own logic.
        # The exit code is in e.code. Logging already done or not needed.
        # Simply re-raise to ensure the script exits with the correct code.
        if logger: logger.info(f"Script explicitly exited with status {e.code}.")
        else: print(f"Script explicitly exited with status {e.code}.", file=sys.stderr)
        raise
    except Exception as e:
        # Catch any other unexpected top-level exceptions
        if logger: # If logger was initialized
            logger.critical(f"Unhandled top-level exception caused script termination: {e}", exc_info=True)
            logger.critical(traceback.format_exc())
        else: # Logger not even initialized, print to stderr
            print(f"CRITICAL: Unhandled top-level exception: {e}", file=sys.stderr)
            print(traceback.format_exc(), file=sys.stderr)
        sys.exit(1) # General error
    finally:
        if logger and not shutdown_event.is_set(): # If not already shutting down via signal
            logger.info("Script __main__ scope is finishing.")
        # Ensure logging handlers are flushed and closed if script exits this way
        # However, if run_capture_service exited cleanly, it would call logging.shutdown()
        # This is a final failsafe.
        if logging.getLogger(SCRIPT_NAME).hasHandlers(): # Check if logger was indeed set up
            logging.shutdown()

配套 systemctl 控制：

[Unit]
Description=Armbian Camera Capture Service
Documentation=https://your-documentation-url-here.com # 可选：指向您的文档
RequiresMountsFor=/opt/camera/captures
After=multi-user.target network.target opt-camera-captures.mount
# 如果明确知道摄像头设备，可以更精确地控制启动顺序
# 例如: Wants=dev-video2.device After=dev-video2.device

[Service]
# ---- 基本配置 ----
Type=simple
WorkingDirectory=/opt/camera
ExecStart=/opt/camera/opencv/bin/python /opt/camera/capture.py
ExecStop=/bin/kill -TERM $MAINPID

# ---- 自动重启策略 ----
Restart=on-failure # 或 'always'。'on-failure' 表示仅在脚本以非0状态退出时重启
RestartSec=10      # 重启前等待10秒
StartLimitIntervalSec=300 # 在300秒内
StartLimitBurst=5         # 最多尝试重启5次，防止无限重启循环

# ---- 日志和环境 ----
Environment="PYTHONUNBUFFERED=1"
StandardOutput=journal # 将Python脚本的stdout重定向到systemd journal
StandardError=journal  # 将Python脚本的stderr重定向到systemd journal
SyslogIdentifier=armbian-camera-capture

# ---- 安全性增强 (重要) ----
# 限制文件系统访问
ProtectSystem=strict     # /usr, /boot, /etc 设为只读
ProtectHome=true         # /home, /root 目录不可访问
PrivateTmp=true          # 使用私有的 /tmp 和 /var/tmp 目录
PrivateDevices=true      # 默认不暴露设备，除非通过 DeviceAllow 明确允许
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_UNIX # 根据需要调整，如果只用本地设备，AF_UNIX可能就够了
RestrictRealtime=true

# 限制权限提升
NoNewPrivileges=true

# 明确允许访问摄像头设备 (假设是 /dev/video2)
# DeviceAllow=/dev/video[1-6] rw
DeviceAllow=/dev/v4l/by-id/usb-Sonix_Technology_Co.__Ltd._UGREEN_Camera_2K_SN0001-video-index0 rw
# 如果还需要访问其他设备 (例如特定USB控制器)，也在此处添加

# 进一步限制能力 (根据脚本实际需要的能力，尽可能减少)
# 对于这个脚本，除了设备访问，可能不需要太多其他特殊能力
CapabilityBoundingSet=~CAP_SYS_ADMIN CAP_NET_ADMIN CAP_SYS_PTRACE CAP_SYS_BOOT CAP_SYS_MODULE CAP_SYS_RAWIO CAP_SYS_TIME CAP_SETUID CAP_SETGID CAP_SETPCAP CAP_LINUX_IMMUTABLE CAP_IPC_LOCK CAP_IPC_OWNER CAP_SYSLOG CAP_MAC_ADMIN CAP_MAC_OVERRIDE CAP_NET_BROADCAST CAP_NET_BIND_SERVICE CAP_AUDIT_CONTROL CAP_AUDIT_READ CAP_AUDIT_WRITE
# 上面是排除了很多不必要的能力，保留了默认需要的一些基本能力。
# 如果脚本非常简单，可以进一步收紧。

# ---- 资源限制 (可选) ----
# LimitNOFILE=1024        # 最大打开文件数
# LimitNPROC=512          # 最大进程数
# CPUQuota=50%            # CPU使用配额
# MemoryMax=512M          # 最大内存使用

# ---- 超时设置 ----
TimeoutStopSec=30s        # 优雅停止的超时时间 (默认90s)

[Install]
WantedBy=multi-user.target

Next-Terminal：家庭内网安全访问解决方案

Fri, 11 Jul 2025 19:43:25 +0800

家庭内网安全访问新方案：Next-Terminal的技术实践与应用

在信息技术快速普及的今天，越来越多的家庭用户搭建起属于自己的服务器、小型 NAS 系统、家庭自动化控制中心等内部 IT 架构。与此同时，如何安全、高效、低成本地从公网访问这些设备，成为一个亟需解决的问题。

开源项目 Next-Terminal（简称 NT）为家庭用户提供了一个优雅的解决方案。它不仅开源、免费，而且资源占用极低（仅约 200MB），性能极高，可以轻松部署在阿里云、腾讯云、轻量云等公网节点上，承担所有流量入口，并将请求安全地转发至家庭内网中的各种服务，真正实现了安全代理与权限控制统一入口管理。

一、家庭网络公网暴露的安全隐患分析

1.1 常见家庭网络暴露方式

假设你在家中部署了一个网站或者 NAS 设备，并希望在外网访问，常见的做法是：

光猫直接进行端口映射（公网 IP）；
直接域名解析至家庭公网 IP（动态 DNS）；
使用 IPv6 地址直连

1.2 潜在安全风险，公网攻击风险高

无论你使用动态域名 + DDNS 还是公网 IPv6 地址，只要设备暴露在公网，就意味着：

被黑客扫描的几率大幅增加；
任何人只要知道你的 IP 地址就能尝试连接；
一旦服务有漏洞（如老旧 NAS、PHP 漏洞），攻击者可能直接入侵内网。

在 IPv4 中，我们普遍使用 NAT（地址转换）将多个内网设备通过一个公网地址上网。但在 IPv6 中，每个设备都可以拥有公网地址，虽然这有助于直连通信，却也带来新的隐患，例如：

地址可预测性，攻击者可通过已知地址推测整个/60前缀范围；
家中每台设备（如路由器、NAS、摄像头、智能电视）都有自己的 IPv6 地址；
攻击者只需知道你服务器的一个 IPv6 地址，即可推测出整个网络前缀范围；
由于 IPv6 地址空间虽大，但仍可进行特定范围段的端口扫描与暴力测试；
很多家庭设备的防火墙并未对 IPv6 有严格配置，一旦开放了某个端口，可能直接被访问。

安全警示：IPv6的全球可达性特性使家庭设备更容易被定位和攻击。

二、Next-Terminal 如何帮你解决以上问题？

Next-Terminal 采用“统一入口代理+精细化权限控制”机制，主要特点包括：

不再暴露内部端口到公网；
只对可信入口开放端口；
支持细粒度访问控制与登录认证；
可审计、可管理、可授权访问你的服务。

graph LR
    A[用户] --> B[NT 公网节点]
    B --> C[家庭网关]
    C --> D[内网服务]

场景模拟：将家庭内网网站安全暴露给公网

假设你家中部署了一个网站（如 http://192.168.1.100:8080），你想在外面访问它，但又不希望任何人都能直接连接。

传统做法：直接端口映射到公网，问题在于安全性欠考量
改进做法：使用 NT 的反向代理+权限验证

实施步骤（有公网地址）：

在公网服务器（如阿里云）上部署 Next-Terminal；
在路由器防火墙中仅允许公网服务器的 IP（如阿里云 IP）访问端口；
添加需要访问的资产（如内网网站）并添加端口映射；
启用认证、授权功能，包括多因素认证以及 Passkey 等；
外部用户通过 Next-Terminal 平台访问，身份校验后由公网服务器代理请求至内部目标服务。

实施步骤（无公网地址）：

在公网服务器（如阿里云）上部署 Next-Terminal；
在家庭路由器中部署 NT 安全网关（轻量容器或小型主机）；
将 NT 网关注册至 NT 平台；
添加需要访问的资产（如内网网站）；
启用认证、授权功能，包括多因素认证以及 Passkey 等；
外部用户通过 NT 平台访问，身份校验后由公网服务器代理请求至家庭网关，再转发至目标服务。

三、防火墙策略：只信任公网服务器，拒绝一切其它访问

为了进一步提升安全性，你可以在家中路由器或软路由中设置如下防火墙规则：

只允许 NT 公网服务器 IP（如阿里云节点）访问指定端口（如 NAS 的 8080）；
阻断其他任何来源 IP 的访问请求。

这种方式实现了“只有我信任的服务器能访问我的家庭内网”，哪怕有人得到了你的公网 IP 地址，也无法连接设备。

# 示例防火墙策略（假设家庭网关使用 iptables）
# 允许阿里云IP访问8080
iptables -A INPUT -p tcp -s <NT公网IP> --dport 8080 -j ACCEPT
# 拒绝其它IP访问8080
iptables -A INPUT -p tcp --dport 8080 -j DROP

四、与传统 VPN、FRP 方案对比

特性	VPN	FRP	NextTerminal ✅
安全性	高（需硬件）	中等（需配置）	高（精细授权）
易用性	外部访问需客户端	配置复杂	网页访问即可
部署难度	简单（硬件）	中	简单（容器部署）
用户权限管理	✅ 支持	不支持	✅ 支持
日志与审计	不便查询	不支持	✅ 支持
内网服务代理能力	✅ 自动配置	需端口映射	✅ 自动代理

五、延伸用途：不仅仅是访问网站

NextTerminal 不仅能代理网站，还能用于：

远程控制家庭 Linux 主机（SSH）；
管理内网 Windows 桌面（RDP）；
查看 NAS 文件目录（甚至WebDAV）；
访问摄像头管理后台；
接入 HomeAssistant、Aria2、Transmission 等家庭服务。

并且一切操作都有统一入口、统一身份认证。

致开发者：开源精神不应被辜负

Next-Terminal 是一款由国人开发、免费开源的安全运维平台，代码托管于 GitHub，开发者持续维护更新。如果你是开发者、运维人员或家庭用户，强烈建议：

亲自体验这款软件的部署流程与使用方式；
给项目一个 Star ⭐️；
在你的博客或社群宣传它；
提出建议或贡献文档，一起完善它！

📘 参考资料与推荐链接

项目地址：https://github.com/dushixiang/next-terminal
文档中心：https://next-terminal.dushixiang.com
IPv6 安全性讨论（Google security paper）：https://research.google/pubs/pub46246/
家庭用户安全配置建议（知乎）：https://zhuanlan.zhihu.com/p/620203743

结语

Next-Terminal 不仅是一款优秀的企业级远程运维平台，它也非常适合家庭用户使用。通过构建统一、安全的访问入口，我们不再需要担心公网攻击、不再依赖繁琐的 VPN 配置，也不需要冒着暴露内网的风险。

家庭 IT 架构的安全，是每一个技术爱好者应当重视的课题。今天，从部署一个 Next-Terminal 开始，提升你的网络安全水平吧。

Hugo 网站搭建入门

Fri, 11 Jul 2025 15:25:51 +0800

本文详细讲解如何在 macOS 环境下，从零开始搭建 Hugo 静态网站，不依赖 Homebrew，包含 Git 主题添加、配置修改、内容创建等关键操作，帮助你快速搭建属于自己的高性能博客。

一、准备工作：下载安装 Hugo 与 Git

1.1 手动下载安装 Hugo

打开 Hugo 官方 Releases 页面。
下载对应 macOS 的扩展版（Extended），如： hugo_extended_0.148.0_darwin-universal.tar.gz。

在终端执行以下命令：

cd ~/Downloads
tar -zxvf hugo_extended_0.148.0_darwin-universal.tar.gz
sudo mv hugo /usr/local/bin/
chmod +x /usr/local/bin/hugo

验证安装：
1

hugo version

确认输出包含 extended 字样。

1.2 安装并确认 Git

macOS 默认自带 Git，如果没有，可按提示安装 Xcode Command Line Tools：

`1`	`git --version`

确保能正常显示 Git 版本号。

二、创建 Hugo 项目

2.1 创建新网站

`1`	`hugo new site www-blog`

其中 www-blog 是新建的文件夹名称，可以随意取名，不影响博客标题或内容，只是项目根目录名称。

2.2 进入项目目录

`1`	`cd www-blog`

三、添加主题

3.1 通过 Git 添加官方主题（以 Ananke 为例）

1
2

git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

提示：如果遇到代理或网络问题，建议手动下载 ZIP 并解压到 themes/ananke 文件夹。

3.2 修改配置文件启用主题

编辑项目根目录下的 hugo.toml，添加或修改如下内容：

baseURL = "http://example.org/"
languageCode = "zh-CN"
title = "我的 Hugo 博客"
theme = "ananke"

四、创建内容文章

4.1 新建一篇 Markdown 文章

`1`	`hugo new posts/hello.md`

4.2 编辑文章内容

打开 content/posts/hello.md，将 draft: true 改为 draft: false，示例内容如下：

---
title: "Hello Hugo"
date: 2025-07-11T14:00:00+08:00
draft: false
---

这是我使用 Hugo 创建的第一篇博客文章。  
欢迎阅读并分享！

五、本地预览网站

启动 Hugo 本地服务器：

`1`	`hugo server -D`

然后打开浏览器访问：

`1`	`http://localhost:1313`

你会看到主题渲染的博客首页和你的文章。

六、生成静态站点文件

退出服务器后，执行：

hugo

静态页面生成在项目根目录的 public/ 文件夹。

七、部署到 GitHub Pages

7.1 新建 GitHub 仓库（假设名为 `www-blog`）

7.2 推送 `public` 文件夹内容到 `gh-pages` 分支

cd public
git init
git remote add origin https://github.com/你的用户名/www-blog.git
git checkout -b gh-pages
git add .
git commit -m "首次部署 Hugo 站点"
git push -f origin gh-pages

7.3 在 GitHub 仓库设置页面开启 GitHub Pages

进入 Settings → Pages
选择 gh-pages 分支作为发布源
保存后等待几分钟即可访问：

`1`	`https://你的用户名.github.io/www-blog/`

八、总结说明

hugo new site <文件夹名> 中的文件夹名只是项目目录名，不影响博客标题或 URL，只是你电脑里的文件夹名称。
博客标题和网站配置在 hugo.toml 中设置，你可以随时修改。
主题通过 Git 子模块添加，也可用手动下载主题 ZIP 包的方式。
写文章时注意将 draft 设置为 false，否则文章不会发布。
本地用 hugo server -D 预览，生成静态站点用 hugo 命令。