Release v0.4.0: 添加配置文件支持和 Gallery 随机模式

主要更新：

1. 配置文件支持
   - 支持 ~/.config/tiklocal/config.yaml 配置文件
   - 添加命令行参数解析（支持 --host, --port）
   - 配置优先级：命令行参数 > 环境变量 > 配置文件 > 默认值
   - 添加 PyYAML 依赖

2. Gallery 随机模式
   - 新增右下角模式切换按钮
   - 支持随机浏览所有层级的图片
   - 无限滚动自动加载
   - 使用 localStorage 持久化用户选择
   - 保持 Pinterest 瀑布流布局

3. 界面优化
   - 修复按钮与底部导航栏的层级问题
   - 优化图片懒加载性能
   - 改进模态框事件绑定逻辑

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ChanMo

CLAUDE.md

@@ -8,7 +8,7 @@ TikLocal is a Flask-based web application that provides a TikTok-like interface
 
 ## Key Dependencies
 
-- **Backend**: Flask 3.1.0, Waitress (WSGI server)
+- **Backend**: Flask 3.1.0, Waitress (WSGI server), PyYAML 6.0 (config file support)
 - **Frontend**: TailwindCSS v4, Feather Icons, Hammer.js
 - **Python**: Requires Python >=3.10,<4.0
 - **Package Management**: Poetry for Python dependencies, npm for CSS building
@@ -33,20 +33,29 @@ npm run build-css-prod
 # Install dependencies
 poetry install
 
-# Run the application
-poetry run tiklocal /path/to/media/folder
+# Run the application (multiple ways)
+poetry run tiklocal /path/to/media/folder       # Direct path argument
+poetry run tiklocal --port 9000                 # Custom port with config file
+MEDIA_ROOT=/path tiklocal                       # Environment variable
+tiklocal                                        # Use config file
 
-# Or run directly
-python -m tiklocal.run
+# Configuration file (optional)
+# Create ~/.config/tiklocal/config.yaml:
+# media_root: /path/to/media
+# host: 0.0.0.0
+# port: 8000
+
+# Get help
+tiklocal --help
 ```
 
 ## Architecture
 
 ### Core Application Structure
 
 - **`tiklocal/app.py`**: Main Flask application factory with all routes and view functions
-- **`tiklocal/run.py`**: Entry point that starts the Waitress WSGI server on port 8000
-- **`tiklocal/config.py`**: Configuration file (currently empty, uses environment variables)
+- **`tiklocal/run.py`**: CLI entry point with argument parsing, config file loading, and Waitress server startup
+- **`tiklocal/config.py`**: Configuration file (currently empty, configuration handled via config file/env vars)
 
 ### Key Routes and Features
 
@@ -74,14 +83,63 @@ python -m tiklocal.run
 
 ### Configuration
 
-- **Environment Variables**: `MEDIA_ROOT` (required) - path to media directory
+The application supports multiple configuration methods with the following priority (highest to lowest):
+
+1. **Command Line Arguments**: Direct arguments passed to `tiklocal`
+   - `tiklocal /path/to/media` - specify media root
+   - `--host HOST` - server host (default: 0.0.0.0)
+   - `--port PORT` - server port (default: 8000)
+
+2. **Environment Variables**:
+   - `MEDIA_ROOT` - path to media directory
+   - `TIKLOCAL_HOST` - server host
+   - `TIKLOCAL_PORT` - server port
+
+3. **Configuration File**: `~/.config/tiklocal/config.yaml` or `~/.tiklocal/config.yaml`
+   ```yaml
+   media_root: /path/to/media
+   host: 0.0.0.0
+   port: 8000
+   ```
+
+4. **Defaults**: host=0.0.0.0, port=8000
+
 - **Instance Config**: Uses Flask's instance-relative configuration
 - **Favorites**: Stored as JSON file in media root directory
 
 ## Development Notes
 
-- The application uses environment variable `MEDIA_ROOT` to determine media location
+- Configuration priority: CLI args > Environment variables > Config file > Defaults
+- Config file locations: `~/.config/tiklocal/config.yaml` or `~/.tiklocal/config.yaml`
 - Templates include responsive design optimized for mobile and tablet usage
 - Custom Jinja2 filters for timestamp and file size formatting
 - Error handling includes user-friendly messages and proper HTTP status codes
-- Dark mode implementation uses CSS custom properties and data attributes
+- Dark mode implementation uses CSS custom properties and data attributes
+
+## Release Process
+
+When publishing a new version to PyPI:
+
+1. **Update version number** in `pyproject.toml`:
+   ```toml
+   version = "x.y.z"
+   ```
+
+2. **Commit changes**:
+   ```bash
+   git add .
+   git commit -m "Release vx.y.z: description of changes"
+   ```
+
+3. **Create and push git tag** (required for PyPI build):
+   ```bash
+   git tag -a vx.y.z -m "Release vx.y.z: description"
+   git push origin vx.y.z
+   ```
+
+4. **Push commits**:
+   ```bash
+   git push
+   ```
+
+**Note**: The git tag triggers the CI/CD pipeline to automatically build and publish to PyPI.

package.json

@@ -3,8 +3,8 @@
   "version": "0.1.6",
   "description": "A local media server that combines the features of TikTok and Pinterest",
   "scripts": {
-    "build-css": "tailwindcss -i ./tiklocal/static/tailwind.css -o ./tiklocal/static/output.css --watch",
-    "build-css-prod": "tailwindcss -i ./tiklocal/static/tailwind.css -o ./tiklocal/static/output.css --minify",
+    "build-css": "tailwindcss -i ./tiklocal/static/input.css -o ./tiklocal/static/output.css --watch",
+    "build-css-prod": "tailwindcss -i ./tiklocal/static/input.css -o ./tiklocal/static/output.css --minify",
     "dev": "npm run build-css",
     "build": "npm run build-css-prod"
   },

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "TikLocal"
-version = "0.3.8"
+version = "0.4.0"
 description = "A local media server that combines the features of TikTok and Pinterest"
 authors = ["ChanMo <chan.mo@outlook.com>"]
 readme = "README.md"
@@ -16,6 +16,7 @@ tiklocal = 'tiklocal.run:main'
 python = ">=3.10,<4.0"
 flask = "^3.1.0"
 waitress = "^3.0.2"
+pyyaml = "^6.0"
 
 [[tool.poetry.source]]
 name = "aliyun"

tiklocal/app.py

@@ -180,6 +180,40 @@ def api_videos():
 
         return json.dumps(res)
 
+    @app.route('/api/random-images')
+    def api_random_images():
+        """ API to get random images with pagination """
+        root = Path(app.config["MEDIA_ROOT"])
+        page = int(request.args.get('page', 1))
+        page_size = int(request.args.get('size', 30))
+
+        # 获取所有图片文件
+        images = []
+        for ext in ['*.jpg', '*.jpeg', '*.png', '*.gif', '*.webp', '*.bmp']:
+            images.extend(root.glob(f'**/{ext}'))
+            images.extend(root.glob(f'**/{ext.upper()}'))
+
+        # 随机打乱（使用固定种子确保同一会话中的一致性）
+        seed = request.args.get('seed', str(random.randint(1, 999999)))
+        random.seed(seed)
+        random.shuffle(images)
+
+        # 分页
+        total = len(images)
+        start = (page - 1) * page_size
+        end = start + page_size
+        page_images = images[start:end]
+
+        res = [str(img.relative_to(root)) for img in page_images]
+
+        return {
+            'images': res,
+            'page': page,
+            'total': total,
+            'has_more': end < total,
+            'seed': seed
+        }
+
 
     @app.route('/settings/')
     def settings_view():

tiklocal/run.py

@@ -1,8 +1,105 @@
+import os
+import sys
+import argparse
+from pathlib import Path
 from waitress import serve
 from tiklocal.app import create_app
 
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+
+def load_config():
+    """从配置文件加载配置"""
+    config = {}
+
+    # 尝试读取配置文件
+    config_paths = [
+        Path.home() / '.config' / 'tiklocal' / 'config.yaml',
+        Path.home() / '.tiklocal' / 'config.yaml',
+    ]
+
+    for config_path in config_paths:
+        if config_path.exists():
+            if yaml is None:
+                print(f"警告: 找到配置文件 {config_path} 但未安装 PyYAML，跳过配置文件", file=sys.stderr)
+                break
+            try:
+                with open(config_path, 'r', encoding='utf-8') as f:
+                    config = yaml.safe_load(f) or {}
+                break
+            except Exception as e:
+                print(f"警告: 读取配置文件 {config_path} 失败: {e}", file=sys.stderr)
+
+    return config
+
+
 def main():
-    serve(create_app(), host='0.0.0.0', port=8000)
+    # 读取配置文件
+    config = load_config()
+
+    # 解析命令行参数
+    parser = argparse.ArgumentParser(
+        description='TikLocal - 本地媒体服务器',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+示例:
+  tiklocal                           # 使用配置文件或环境变量
+  tiklocal /path/to/media            # 指定媒体目录
+  tiklocal --port 9000               # 使用指定端口
+  tiklocal /path/to/media --port 9000
+        '''
+    )
+
+    parser.add_argument(
+        'media_root',
+        nargs='?',
+        help='媒体文件根目录路径'
+    )
+    parser.add_argument(
+        '--host',
+        default=None,
+        help='服务器监听地址 (默认: 0.0.0.0)'
+    )
+    parser.add_argument(
+        '--port',
+        type=int,
+        default=None,
+        help='服务器端口 (默认: 8000)'
+    )
+
+    args = parser.parse_args()
+
+    # 配置优先级: 命令行参数 > 环境变量 > 配置文件 > 默认值
+    media_root = args.media_root or os.environ.get('MEDIA_ROOT') or config.get('media_root')
+    host = args.host or os.environ.get('TIKLOCAL_HOST') or config.get('host', '0.0.0.0')
+    port = args.port or int(os.environ.get('TIKLOCAL_PORT', 0)) or config.get('port', 8000)
+
+    # 验证媒体目录
+    if not media_root:
+        parser.error('必须指定媒体目录:\n  - 通过命令行参数: tiklocal /path/to/media\n  - 通过环境变量: MEDIA_ROOT=/path/to/media\n  - 通过配置文件: ~/.config/tiklocal/config.yaml')
+
+    media_path = Path(media_root)
+    if not media_path.exists():
+        print(f"错误: 媒体目录不存在: {media_root}", file=sys.stderr)
+        sys.exit(1)
+
+    if not media_path.is_dir():
+        print(f"错误: 路径不是目录: {media_root}", file=sys.stderr)
+        sys.exit(1)
+
+    # 设置环境变量供 Flask 使用
+    os.environ['MEDIA_ROOT'] = str(media_path.absolute())
+
+    # 启动服务器
+    print(f"启动 TikLocal 服务器...")
+    print(f"媒体目录: {media_path.absolute()}")
+    print(f"访问地址: http://{host}:{port}")
+
+    serve(create_app(), host=host, port=port)
+
 
 if __name__ == '__main__':
     main()

tiklocal/static/output.css

@@ -5,6 +5,7 @@
     <title>TikLocal</title>
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <link rel="stylesheet" type="text/css" href="{{url_for('static', filename='output.css')}}">
+    <script src="{{url_for('static', filename='feather.min.js')}}"></script>
     {% block extra_head %}{% endblock %}
   </head>
   <body data-theme="{{ theme if theme else 'light' }}" class="bg-gray-50 dark:bg-gray-900 text-gray-900 dark:text-white min-h-screen pb-16 transition-colors duration-300">
@@ -39,7 +40,6 @@
     </nav>
 
     {% block extra_body %}{% endblock %}
-    <script src="{{url_for('static', filename='feather.min.js')}}"></script>
     <script>
       // 主题管理类
       class ThemeManager {