[{"content":"","date":"2026-05-09","externalUrl":null,"permalink":"/","section":"","summary":"","title":"","type":"page"},{"content":"","date":"2026-05-09","externalUrl":null,"permalink":"/open-source/","section":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","summary":"","title":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","type":"open-source"},{"content":" CCSwitch 使用中转 API 教程 # 本文档用于指导你在 CCSwitch 中使用统一中转 API。\n请注意：你只需要使用中转 API 地址和令牌，不需要也不应该填写任何上游平台的原始 API Key。\n一、准备信息 # 请先向管理员获取以下信息：\nBase URL：https://api.hellcious.lol/v1 API Key：由自己分配的 One API 令牌，通常以 sk- 开头 模型名称：例如 qwen3.6-plus、deepseek-v3.2、glm-5、mimo-v2.5-pro 示例：\nBase URL：https://api.hellcious.lol/v1 API Key：sk-xxxxxxxxxxxxxxxx Model：qwen3.6-plus 二、在 CCSwitch 中添加配置 # 打开 CCSwitch，进入供应商或 API 配置页面。\n选择：\n添加供应商 / Add Provider 自定义 / Custom OpenAI Compatible / OpenAI 兼容 然后填写：\n名称：Hellcious One API Base URL：https://api.hellcious.lol/v1 API Key：填写你的 sk- 令牌 模型：填写管理员提供的模型名称（可通过获取模型列表来确认） 推荐在opencode中使用（经过测试） 三、获取模型列表是什么意思 # CCSwitch 里的“获取模型列表”会请求：\nhttps://api.hellcious.lol/v1/models 它的作用是自动读取当前令牌可用的模型，避免手动输入模型名。\n如果获取失败，也可以手动填写模型名称。模型名称必须和管理员提供的一致，大小写也要一致。\n四、手动配置模型 JSON # 如果 CCSwitch 需要手动填写模型配置，可以参考：\n[ { \u0026#34;id\u0026#34;: \u0026#34;qwen3.6-plus\u0026#34;, \u0026#34;name\u0026#34;: \u0026#34;Qwen 3.6 Plus\u0026#34; }, { \u0026#34;id\u0026#34;: \u0026#34;deepseek-v3.2\u0026#34;, \u0026#34;name\u0026#34;: \u0026#34;DeepSeek V3.2\u0026#34; }, { \u0026#34;id\u0026#34;: \u0026#34;glm-5\u0026#34;, \u0026#34;name\u0026#34;: \u0026#34;GLM 5\u0026#34; }, { \u0026#34;id\u0026#34;: \u0026#34;mimo-v2.5-pro\u0026#34;, \u0026#34;name\u0026#34;: \u0026#34;Mimo V2.5 Pro\u0026#34; } ] 说明：\nid：真实请求使用的模型名，不能写错 name：界面显示名称，可以自定义 五、测试是否可用 # 保存配置后，点击 CCSwitch 的测试按钮。\n如果测试通过，说明：\nBase URL 可以连接 API Key 可用 模型基本可用 之后在支持 OpenAI 兼容 API 的工具中选择该配置即可。\n六、常见错误 # 1. 401 Unauthorized # 通常是 API Key 错误。\n请检查：\n是否复制完整 是否包含多余空格 是否使用了管理员分配的 One API 令牌 不要填写 Mimo、阿里百炼等上游平台的原始 Key。\n2. 404 Not Found # 通常是 Base URL 写错。\n正确写法：\nhttps://api.hellcious.lol/v1 不要写成：\nhttps://api.hellcious.lol 3. 400 Not supported model # 通常是模型名写错，或者当前令牌没有权限使用该模型。\n请确认模型名完全一致，例如：\nmimo-v2.5-pro 不要写成：\nMiMo-V2.5-Pro 模型名大小写可能敏感。\n确认可用后，再切换到其他模型。\n七、安全注意事项 # 请妥善保管你的 API Key：\n不要发到公开群聊 不要提交到 GitHub 不要写进前端网页代码 不要分享给其他人 如果怀疑 Key 泄露，请自行重新生成。\n","date":"2026-05-09","externalUrl":null,"permalink":"/open-source/oneapi_guide/","section":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","summary":"","title":"One API 使用教程","type":"open-source"},{"content":"","date":"2026-05-09","externalUrl":null,"permalink":"/tags/open-source/","section":"Tags","summary":"","title":"Open-Source","type":"tags"},{"content":"","date":"2026-05-09","externalUrl":null,"permalink":"/tags/","section":"Tags","summary":"","title":"Tags","type":"tags"},{"content":" PowerShell 终端美化完全指南 # 将 Windows 原生终端打造为类 Linux（oh-my-zsh）的高效开发环境。\n效果预览 # 美化后的 PowerShell 终端将具备以下特性：\n彩色提示符：显示当前目录、Git 分支、执行时间 智能补全：输入时自动联想历史命令 图标支持：文件、文件夹、Git 状态可视化图标 快速跳转：智能目录记忆与模糊搜索 第一步：安装核心工具 # 1.1 安装 PowerShell 7 # # 使用 winget 安装最新版 PowerShell winget install --id Microsoft.Powershell --source winget # 安装完成后，在开始菜单搜索 \u0026#34;PowerShell\u0026#34; 启动 1.2 安装 Oh My Posh # # 安装主题美化工具 winget install JanDeDobbeleer.OhMyPosh --source winget # 安装 Nerd Font（解决图标显示问题） oh-my-posh font install # 推荐选择：JetBrainsMono Nerd Font 或 MesloLGS NF 1.3 安装辅助工具 # # 智能目录跳转 winget install ajeetdsouza.zoxide # 模糊搜索工具 winget install junegunn.fzf # Git 状态显示 Install-Module posh-git -Force 第二步：配置 PowerShell 配置文件 # 2.1 打开配置文件 # # 如果文件不存在，会自动创建 notepad $PROFILE 2.2 完整配置内容 # 将以下内容复制到 $PROFILE 文件中：\n# ============================================ # PowerShell 美化配置文件 # ============================================ # 1. 初始化 Oh My Posh（主题美化） oh-my-posh init pwsh --config $env:POSH_THEMES_PATH\\ys.omp.json | Invoke-Expression # 2. 配置 PSReadLine（智能补全） Set-PSReadLineOption -PredictionSource History Set-PSReadLineOption -PredictionViewStyle InlineView Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete # 3. 初始化 Zoxide（智能目录跳转） Invoke-Expression (\u0026amp; { (zoxide init powershell | Out-String) }) # 4. 导入 Posh-Git（Git 状态显示） Import-Module posh-git # 5. 设置别名（可选） Set-Alias -Name z -Value __zoxide_z Set-Alias -Name zi -Value __zoxide_zi # 6. 启用 FZF（模糊搜索） Set-PsFzfOption -PSReadlineChordProvider \u0026#39;Ctrl+t\u0026#39; -PSReadlineChordReverseHistory \u0026#39;Ctrl+r\u0026#39; 2.3 保存并生效 # # 保存文件后，重新加载配置 . $PROFILE # 或者重启 PowerShell 第三步：配置 Windows Terminal # 3.1 设置默认字体 # 打开 Windows Terminal 按 Ctrl + , 打开设置 选择 PowerShell 配置文件 点击 外观 将 字体 设置为 JetBrainsMono Nerd Font 3.2 设置默认启动 # 在设置中选择 启动 将 默认配置文件 设置为 PowerShell 将 默认终端应用程序 设置为 Windows Terminal 第四步：验证安装 # 4.1 检查各组件状态 # # 检查 PowerShell 版本 $PSVersionTable.PSVersion # 检查 Oh My Posh 版本 oh-my-posh version # 检查 Zoxide 版本 zoxide --version # 检查 FZF 版本 fzf --version 4.2 测试功能 # # 测试智能补全：输入 \u0026#34;cd Do\u0026#34; 应该显示历史目录 # 测试 Zoxide：输入 \u0026#34;z doc\u0026#34; 跳转到 Documents 目录 # 测试 FZF：按 Ctrl+R 搜索历史命令 # 测试 Git 显示：进入 Git 仓库，查看提示符是否显示分支名 第五步：常用快捷键 # 5.1 命令编辑 # 快捷键 功能 Ctrl + A 跳到行首 Ctrl + E 跳到行尾 Ctrl + U 删除光标前所有字符 Ctrl + K 删除光标后所有字符 Ctrl + W 删除前一个单词 Ctrl + L 清屏 5.2 历史命令 # 快捷键 功能 ↑ / ↓ 浏览历史命令 Ctrl + R 模糊搜索历史（FZF） Tab 自动补全 5.3 Windows Terminal # 快捷键 功能 Ctrl + Shift + T 新建标签页 Ctrl + Shift + W 关闭标签页 Ctrl + Tab 切换标签页 Shift + Alt + + 横向分屏 Shift + Alt + - 纵向分屏 常见问题解决 # 问题 1：执行策略限制 # 错误信息：\n无法加载文件，因为在此系统上禁止运行脚本 解决方法：\n# 修改执行策略 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser # 确认选择 Y 问题 2：图标显示为方框 # 原因：未安装 Nerd Font 或字体设置错误\n解决方法：\n确认已运行 oh-my-posh font install 在 Windows Terminal 设置中，将字体改为 JetBrainsMono Nerd Font 重启终端 问题 3：Oh My Posh 未生效 # 检查步骤：\n# 1. 检查配置文件是否存在 Test-Path $PROFILE # 2. 查看配置文件内容 cat $PROFILE # 3. 手动加载配置 . $PROFILE 问题 4：启动速度慢 # 优化方法：\n# 使用静态主题（更快） oh-my-posh init pwsh --print | Invoke-Expression # 或者禁用部分模块 # 注释掉 $PROFILE 中不需要的模块 进阶配置 # 自定义主题 # # 查看所有可用主题 Get-PoshThemes # 使用其他主题（例如 powerlevel10k） oh-my-posh init pwsh --config $env:POSH_THEMES_PATH\\powerlevel10k.omp.json | Invoke-Expression 自定义提示符 # 创建自定义主题文件 ~/.mytheme.omp.json：\n{ \u0026#34;$schema\u0026#34;: \u0026#34;https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json\u0026#34;, \u0026#34;blocks\u0026#34;: [ { \u0026#34;type\u0026#34;: \u0026#34;prompt\u0026#34;, \u0026#34;alignment\u0026#34;: \u0026#34;left\u0026#34;, \u0026#34;segments\u0026#34;: [ { \u0026#34;type\u0026#34;: \u0026#34;path\u0026#34;, \u0026#34;style\u0026#34;: \u0026#34;powerline\u0026#34;, \u0026#34;powerline_symbol\u0026#34;: \u0026#34;\\uE0B0\u0026#34;, \u0026#34;foreground\u0026#34;: \u0026#34;#ffffff\u0026#34;, \u0026#34;background\u0026#34;: \u0026#34;#61AFEF\u0026#34;, \u0026#34;template\u0026#34;: \u0026#34; {{ .Path }} \u0026#34; } ] } ] } 完整配置一键安装脚本 # # 保存为 Install-PowerShellTools.ps1 并执行 # 安装 PowerShell 7 winget install --id Microsoft.Powershell --source winget # 安装 Oh My Posh winget install JanDeDobbeleer.OhMyPosh --source winget # 安装字体 oh-my-posh font install # 安装 Zoxide winget install ajeetdsouza.zoxide # 安装 FZF winget install junegunn.fzf # 安装 Posh-Git Install-Module posh-git -Force # 创建配置文件 $profileContent = @\u0026#39; # Oh My Posh oh-my-posh init pwsh --config $env:POSH_THEMES_PATH\\ys.omp.json | Invoke-Expression # PSReadLine Set-PSReadLineOption -PredictionSource History Set-PSReadLineOption -PredictionViewStyle InlineView # Zoxide Invoke-Expression (\u0026amp; { (zoxide init powershell | Out-String) }) # Posh-Git Import-Module posh-git # 别名 Set-Alias -Name z -Value __zoxide_z Set-Alias -Name zi -Value __zoxide_zi \u0026#39;@ # 确保目录存在 if (!(Test-Path (Split-Path $PROFILE))) { New-Item -ItemType Directory -Path (Split-Path $PROFILE) -Force } # 写入配置文件 $profileContent | Out-File -FilePath $PROFILE -Encoding utf8 # 设置执行策略 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force Write-Host \u0026#34;安装完成！请重启 PowerShell 并运行 . `$PROFILE\u0026#34; -ForegroundColor Green 参考资料 # Oh My Posh 官方文档 PowerShell 文档 Windows Terminal 文档 Zoxide GitHub FZF GitHub 提示：配置完成后，建议重启 Windows Terminal 以确保所有更改生效。\n","date":"2026-04-15","externalUrl":null,"permalink":"/open-source/powershell_beautify/","section":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","summary":"","title":"PowerShell 终端美化完全指南：从安装到配置","type":"open-source"},{"content":" PairDrop 自托管部署指南 # 本指南详细记录了 PairDrop 自托管服务的完整部署流程，涵盖从基础环境搭建到生产环境配置的各个步骤。通过遵循本指南，您可以在 VPS 服务器上成功部署 PairDrop，实现局域网外的文件传输功能。\n目录 # 环境准备与前置条件 Docker 环境安装 PairDrop 容器部署 Caddy 反向代理配置 WebSocket 配置详解 SSL 证书配置 Docker 网络配置 防火墙与端口设置 环境变量优化 调试与日志分析 常见问题与解决方案 环境准备与前置条件 # 服务器要求 # 部署 PairDrop 建议使用具有公网 IP 的 VPS 服务器，最低配置要求如下：CPU 至少 1 核心，内存不少于 1GB，硬盘空间 5GB 以上即可。操作系统推荐使用 Ubuntu 20.04/22.04 或 Debian 11/12，这些系统对 Docker 的支持最为完善，社区资料也最为丰富。\n域名准备 # PairDrop 的 WebSocket 功能需要通过 HTTPS 访问，因此您需要准备一个已备案的域名（针对中国大陆服务器）。域名需要在 DNS 服务商处添加 A 记录，指向您的服务器公网 IP。如果您使用 Cloudflare 等 CDN 服务，需要将 DNS 记录设置为 DNS Only 模式（灰色云朵）或 Proxied 模式（橙色云朵），两种模式均可正常工作，但需要注意 SSL 证书的配置方式有所不同。\n端口要求 # 服务器防火墙需要开放以下端口：80 端口用于 Caddy 自动申请 Let\u0026rsquo;s Encrypt 证书（HTTP 挑战），443 端口用于 HTTPS 访问和 WebSocket 连接。其他端口如需远程管理，可以根据实际需求开放 SSH（默认 22）、Caddy 管理界面（2019）等。\nDocker 环境安装 # 安装 Docker # 首先更新系统软件包索引，执行以下命令安装基础依赖：\nsudo apt update \u0026amp;\u0026amp; sudo apt upgrade -y 安装 Docker 的推荐方式是使用官方安装脚本，该脚本会自动检测系统环境并完成安装：\ncurl -fsSL https://get.docker.com | sh -s -- --mirror Aliyun 安装完成后，将当前用户添加到 docker 用户组，这样无需 sudo 即可执行 Docker 命令：\nsudo usermod -aG docker $USER 执行完上述命令后，建议重新登录 shell 会话以使组成员资格生效。验证 Docker 是否正确安装，可以运行：\ndocker --version docker compose version 配置 Docker 镜像加速（可选） # 中国大陆用户可以使用国内镜像加速器来提高 Docker 镜像的下载速度。编辑 Docker 配置文件：\nsudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json \u0026lt;\u0026lt;EOF { \u0026#34;registry-mirrors\u0026#34;: [ \u0026#34;https://docker.mirrors.ustc.edu.cn\u0026#34;, \u0026#34;https://hub-mirror.c.163.com\u0026#34; ] } EOF 重启 Docker 服务使配置生效：\nsudo systemctl daemon-reload sudo systemctl restart docker PairDrop 容器部署 # 创建项目目录 # 为了便于管理，建议在服务器上创建一个专门用于 PairDrop 的目录结构：\nsudo mkdir -p /opt/pairdrop cd /opt/pairdrop 编写 Docker Compose 配置文件 # 在项目目录下创建 docker-compose.yml 文件，这是部署 PairDrop 容器的核心配置：\nsudo nano /opt/pairdrop/docker-compose.yml 文件内容如下：\nversion: \u0026#34;3.8\u0026#34; services: pairdrop: image: ghcr.io/schlagmichdoch/pairdrop:latest container_name: pairdrop restart: unless-stopped environment: - WS_FALLBACK=false - DEBUG_MODE=false networks: - pairdrop-network networks: pairdrop-network: name: pairdrop-network driver: bridge 上述配置说明如下：image 指定使用 GitHub Container Registry 上的最新 PairDrop 镜像；restart 策略设为 unless-stopped，确保容器在服务器重启后自动启动；WS_FALLBACK 设置为 false，用于在排查问题时暴露 WebSocket 相关错误，生产环境可根据需要调整；DEBUG_MODE 设为 false 以减少日志输出，调试时可改为 true。\n启动 PairDrop 容器 # 执行以下命令拉取镜像并启动容器：\ncd /opt/pairdrop sudo docker compose up -d 验证容器是否正常运行：\nsudo docker ps | grep pairdrop 如果容器状态显示为 Up 且没有 Restarting 字样，说明 PairDrop 基础服务已成功启动。此时可以通过服务器内网 IP 的默认端口（需要查看镜像文档）访问服务，验证其基本功能是否正常。\nCaddy 反向代理配置 # PairDrop 需要通过 WebSocket 进行实时通信，而 WebSocket 依赖 HTTP 协议升级机制。使用 Caddy 作为反向代理是推荐方案，因为它能自动处理 SSL 证书且配置简洁。\n安装 Caddy # Caddy 的安装同样推荐使用官方安装脚本：\nsudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl curl -1sLf \u0026#39;https://dl.cloudsmith.io/public/caddy/stable/gpg.key\u0026#39; | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg curl -1sLf \u0026#39;https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt\u0026#39; | sudo tee /etc/apt/sources.list.d/caddy-stable.list sudo apt update sudo apt install caddy 安装完成后，Caddy 服务会自动启动并监听 80 和 443 端口。\n创建 Caddy 配置目录 # sudo mkdir -p /opt/pairdrop/caddy cd /opt/pairdrop/caddy 编写 Caddyfile 配置 # 创建 Caddyfile，这是 Caddy 的核心配置文件：\nsudo nano /opt/pairdrop/caddy/Caddyfile 对于使用 Cloudflare 的用户，推荐配置如下（请将 your-domain.com 替换为您的实际域名）：\nyour-domain.com { reverse_proxy localhost:3000 @websockets { header Connection *Upgrade* header Upgrade websocket path /server } reverse_proxy @websockets localhost:3000 } 上述配置的含义如下：reverse_proxy localhost:3000 将 HTTPS 请求转发到本地的 PairDrop 服务；@websockets 定义了一个命名匹配器，用于识别 WebSocket 连接请求；header 指令设置了 WebSocket 协议升级所需的头部信息；path /server 指定只对 /server 路径的请求应用 WebSocket 转发规则。\n如果您不使用 Cloudflare 或希望 Caddy 自动申请 Let\u0026rsquo;s Encrypt 证书，可以使用以下简化配置：\nyour-domain.com { reverse_proxy localhost:3000 @websockets { header Connection *Upgrade* header Upgrade websocket path /server } reverse_proxy @websockets localhost:3000 } Caddy 与 Docker 容器集成 # 由于 PairDrop 运行在 Docker 容器中，而 Caddy 可能运行在宿主机上或另一个容器中，需要确保两者之间能够正常通信。如果 Caddy 也使用 Docker 部署，需要创建共享网络并正确配置容器间的通信。\nWebSocket 配置详解 # WebSocket 是 PairDrop 实现设备发现和文件传输的核心技术，正确的 WebSocket 配置是部署成功的关键。\nWebSocket 协议升级原理 # WebSocket 是一种在单个 TCP 连接上提供全双工通信的协议。与传统 HTTP 请求-响应模式不同，WebSocket 允许服务器主动向客户端推送数据。协议升级过程如下：客户端发送带有 Upgrade 头部的 HTTP 请求；服务器响应 101 Switching Protocols 状态码；连接从 HTTP 切换为 WebSocket，之后的所有通信都使用 WebSocket 帧格式。\n反向代理 WebSocket 配置要点 # 在 Nginx 中的关键配置如下：\nproxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection \u0026#34;upgrade\u0026#34;; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; 在 Caddy 中的等效配置如下：\n@websockets { header Connection *Upgrade* header Upgrade websocket path /server } reverse_proxy @websockets localhost:3000 两种配置的核心要点一致：设置 Upgrade 头部为 websocket，设置 Connection 头部为 upgrade，添加 X-Forwarded-For 和 X-Forwarded-Proto 头部以传递客户端真实信息。\n常见 WebSocket 连接问题 # WebSocket 连接失败通常表现为浏览器控制台报错 \u0026ldquo;WebSocket connection failed\u0026rdquo; 或 \u0026ldquo;无法建立到 wss://xxx/server 的连接\u0026rdquo;。排查方向包括：检查反向代理是否正确添加了 Upgrade 和 Connection 头部；验证后端服务是否在监听正确端口；确认防火墙允许 WebSocket 握手请求通过；检查 SSL 证书是否有效，自签名证书可能导致浏览器阻止连接。\nSSL 证书配置 # HTTPS 是现代 Web 应用的标配，PairDrop 的 WebSocket 功能要求使用 WSS（WebSocket Secure）协议，这依赖有效的 SSL 证书。\nLet\u0026rsquo;s Encrypt 自动证书 # Caddy 默认会自动从 Let\u0026rsquo;s Encrypt 申请和管理 SSL 证书，这是最简单的方式。前提条件是域名 DNS 已正确解析到服务器 IP，且 80 端口未被占用。首次访问域名时，Caddy 会自动完成证书申请过程。\nCloudflare 源证书 # 如果您的域名使用 Cloudflare CDN，可以选择使用 Cloudflare 提供的源证书。源证书由 Cloudflare 签发，只能用于 Cloudflare 与源服务器之间的加密通信。在 Cloudflare 控制面板的 SSL/TLS -\u0026gt; 源服务器证书中生成源证书，将证书和私钥保存到服务器，然后在 Caddyfile 中指定证书路径。\n自签名证书（仅用于测试） # 自签名证书不推荐用于生产环境，但如果仅用于内网测试，可以通过以下方式生成：\nsudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \\ -keyout /opt/pairdrop/caddy/selfsigned.key \\ -out /opt/pairdrop/caddy/selfsigned.crt \\ -subj \u0026#34;/C=CN/ST=State/L=City/O=Organization/CN=your-domain.com\u0026#34; 在 Caddyfile 中引用自签名证书：\nyour-domain.com { tls /etc/caddy/certs/selfsigned.crt /etc/caddy/certs/selfsigned.key reverse_proxy localhost:3000 } 使用自签名证书时，用户首次访问会看到浏览器的安全警告，需要手动信任证书才能正常使用。\nDocker 网络配置 # Docker 网络配置是容器间通信的基础，正确的网络设置能避免很多连接问题。\n创建自定义 Docker 网络 # 推荐为 PairDrop 创建一个专用的桥接网络，这样便于管理和隔离：\nsudo docker network create pairdrop-network 修改 docker-compose.yml # 更新配置文件以使用指定网络：\nversion: \u0026#34;3.8\u0026#34; services: pairdrop: image: ghcr.io/schlagmichdoch/pairdrop:latest container_name: pairdrop restart: unless-stopped environment: - WS_FALLBACK=false - DEBUG_MODE=false networks: - pairdrop-network ports: - \u0026#34;127.0.0.1:3000:3000\u0026#34; networks: pairdrop-network: external: true name: pairdrop-network 关键是 ports 配置中的 127.0.0.1 前缀，这只允许本地访问，防止端口暴露到公网。所有外部访问都通过反向代理进行。\nCaddy Docker 容器配置 # 如果 Caddy 也运行在 Docker 中，需要确保它与 PairDrop 在同一网络：\nversion: \u0026#34;3.8\u0026#34; services: pairdrop: image: ghcr.io/schlagmichdoch/pairdrop:latest container_name: pairdrop restart: unless-stopped environment: - WS_FALLBACK=false networks: - pairdrop-network expose: - \u0026#34;3000\u0026#34; caddy: image: caddy:2-alpine container_name: pairdrop-caddy restart: unless-stopped volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - ./data:/data - ./config:/config networks: - pairdrop-network ports: - \u0026#34;80:80\u0026#34; - \u0026#34;443:443\u0026#34; - \u0026#34;2019:2019\u0026#34; networks: pairdrop-network: external: true 防火墙与端口设置 # UFW 防火墙配置 # 如果服务器使用 UFW 防火墙，需要开放 HTTP 和 HTTPS 端口：\nsudo ufw allow 80/tcp sudo ufw allow 443/tcp # 如果需要 SSH 管理 sudo ufw allow 22/tcp # 如果需要 Caddy 管理界面 sudo ufw allow 2019/tcp sudo ufw enable sudo ufw status verbose iptables 防火墙配置 # 对于使用 iptables 的服务器：\nsudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT sudo iptables -L -n 云服务器安全组设置 # 如果使用阿里云、腾讯云、AWS 等云服务器，还需要配置云平台的安全组规则，放行 80 和 443 端口的入站流量。\n环境变量优化 # PairDrop 支持多个环境变量来控制其行为，合理的配置能提高服务的稳定性和可调试性。\n常用环境变量说明 # WS_FALLBACK 用于控制 WebSocket 降级模式。当设置为 false 时，如果 WebSocket 连接失败，用户会看到明确的错误提示，这有助于排查问题。设置为 true 时，系统会自动降级到轮询等替代方案，但这会牺牲实时性和性能，生产环境建议保持 false。\nDEBUG_MODE 用于启用调试模式。当设置为 true 时，PairDrop 会输出详细的日志信息，包括 WebSocket 连接详情、客户端信息、错误堆栈等。这些信息对于排查问题非常有价值，但会增加日志量，生产环境建议保持 false。\n生产环境推荐配置 # environment: - WS_FALLBACK=false - DEBUG_MODE=false 调试阶段配置 # 排查问题时可以临时启用调试模式：\nenvironment: - WS_FALLBACK=false - DEBUG_MODE=true 查看容器日志：\nsudo docker logs -f pairdrop 调试与日志分析 # 查看容器日志 # 查看 PairDrop 容器日志的基本命令：\nsudo docker logs pairdrop sudo docker logs --tail 100 pairdrop sudo docker logs -f pairdrop -f 参数会持续跟踪日志输出，类似于 tail -f 的效果。Ctrl+C 可以退出跟踪模式。\n查看 Caddy 日志 # 如果 Caddy 作为 Docker 容器运行：\nsudo docker logs pairdrop-caddy sudo docker logs --tail 100 pairdrop-caddy 查看 Caddy 日志文件（如果配置了文件日志）：\nsudo tail -f /var/log/caddy/access.log sudo tail -f /var/log/caddy/error.log 浏览器开发者工具 # 浏览器开发者工具是排查 WebSocket 问题的利器。在 Firefox 或 Chrome 中按 F12 打开开发者工具，切换到「网络」标签，勾选「过滤 WebSocket」或输入 ws:// 或 wss:// 筛选，然后刷新页面观察 WebSocket 连接请求。\n「控制台」标签会显示 WebSocket 连接的错误信息，如 \u0026ldquo;Firefox 无法建立到 wss://xxx/server 的连接\u0026rdquo;，这些信息是定位问题的关键线索。\n网络抓包分析 # 对于复杂问题，可以使用 tcpdump 或 Wireshark 进行网络抓包：\nsudo tcpdump -i any -n port 443 -w /tmp/https.pcap 然后使用 Wireshark 分析抓包文件，重点关注 TLS 握手和 WebSocket 升级过程。\n常见问题与解决方案 # 问题一：WebSocket 连接失败 # 现象：浏览器控制台报错 \u0026ldquo;WebSocket connection failed\u0026rdquo;，页面显示\u0026quot;连接中\u0026quot;。\n原因：反向代理未正确配置 WebSocket 协议升级。\n解决：确保反向代理配置包含以下头部：\nUpgrade: websocket Connection: upgrade 参考本文档「WebSocket 配置详解」章节的配置示例。\n问题二：Caddy 容器持续重启 # 现象：docker ps 显示容器状态为 Restarting，docker logs 显示错误信息。\n原因：常见原因包括 Caddyfile 语法错误、证书文件路径错误、Docker 网络不存在等。\n解决：按以下步骤排查：\n检查 Caddyfile 语法是否正确，文件路径是否使用了正确的绝对路径。 如果使用自定义证书，确认证书文件存在且权限正确。 确认 Docker 网络已创建，使用 docker network ls 检查。 查看完整错误日志，docker logs \u0026ndash;tail 200 pairdrop-caddy。 问题三：Let\u0026rsquo;s Encrypt 证书申请失败 # 现象：Caddy 日志显示 \u0026ldquo;certificate provisioning for domain failed\u0026rdquo;。\n原因：域名 DNS 未正确解析到服务器 IP、80 端口被其他服务占用、Let\u0026rsquo;s Encrypt 频率限制等。\n解决：\n确认域名 DNS 已生效，使用 ping 或 nslookup 验证。 检查 80 端口是否有其他服务占用，sudo lsof -i :80。 等待一段时间后重试，Let\u0026rsquo;s Encrypt 有频率限制。 查看 Caddy 日志获取详细的错误原因。 问题四：Cloudflare 521 错误 # 现象：通过 Cloudflare 访问时返回 521 错误码。\n原因：Cloudflare 无法连接到源服务器，可能是因为源服务器防火墙阻止了 Cloudflare IP 段。\n解决：\n确认服务器防火墙允许所有来源的 80/443 入站流量。 检查 Cloudflare 源 IP 范围是否被特别限制。 临时将 Cloudflare DNS 设置为 DNS Only 测试。 确认服务器 Web 服务正常运行。 问题五：证书 525 SSL 握手失败 # 现象：Cloudflare SSL 握手失败，错误码 525。\n原因：服务器 SSL 配置与 Cloudflare 不兼容，常见于使用 Cloudflare 源证书但配置错误的情况。\n解决：\n如果使用 Cloudflare 源证书，确认证书链完整。 确认服务器支持 Cloudflare 要求的 TLS 版本（通常需要 TLS 1.2+）。 检查 Caddyfile 中的 tls 配置是否正确。 尝试使用 Caddy 自动申请的 Let\u0026rsquo;s Encrypt 证书。 问题六：自签名证书浏览器不信任 # 现象：页面能打开但 WebSocket 连接失败，浏览器控制台显示证书错误。\n原因：浏览器不信任自签名证书。\n解决：\n导出证书并手动导入到系统受信任根证书颁发机构。 建议改用 Let\u0026rsquo;s Encrypt 免费证书，这是最简单的解决方案。 如果必须使用自签名，确保证书包含正确的域名 CN。 完整部署检查清单 # 部署完成后，使用以下清单进行最终验证：\n基础连通性检查 # 服务器公网 IP 可以 ping 通 域名 DNS 正确解析到服务器 IP 80 和 443 端口防火墙已开放 Docker 服务检查 # Docker 和 Docker Compose 已正确安装 pairdrop 容器状态为 Up pairdrop-caddy 容器状态为 Up（如果使用 Docker 部署 Caddy） 容器未出现 Restarting 状态 功能验证检查 # 通过 HTTPS 访问域名可以打开 PairDrop 页面 页面显示\u0026quot;已连接\u0026quot;而非\u0026quot;连接中\u0026quot; 浏览器控制台无 WebSocket 错误 网络标签页可见成功的 WebSocket 连接（状态码 101） 安全配置检查 # 使用有效的 SSL 证书（非自签名用于生产） HTTP 自动重定向到 HTTPS Caddy 管理界面已限制访问或使用强密码 维护与更新 # 更新 PairDrop # PairDrop 镜像会定期更新，添加新功能和修复问题。更新步骤如下：\ncd /opt/pairdrop sudo docker compose pull sudo docker compose up -d sudo docker image prune -f 更新 Caddy # sudo apt update \u0026amp;\u0026amp; sudo apt upgrade caddy sudo systemctl restart caddy 备份配置 # 定期备份重要配置文件：\nsudo tar -czvf pairdrop-backup-$(date +%Y%m%d).tar.gz \\ /opt/pairdrop/docker-compose.yml \\ /opt/pairdrop/caddy/Caddyfile \\ /opt/pairdrop/caddy/data \\ /opt/pairdrop/caddy/config 总结 # PairDrop 自托管部署的核心要点包括：使用 Docker 容器化部署便于管理；Caddy 反向代理提供简洁的 WebSocket 配置和自动 SSL 证书管理；正确的网络配置确保容器间通信畅通；完善的安全设置保护服务安全。遵循本指南的步骤，您应该能够成功部署一个稳定运行的 PairDrop 服务。\n如果在部署过程中遇到本指南未涵盖的问题，欢迎提供详细的错误信息，以便进一步排查和补充文档。\n","date":"2026-02-09","externalUrl":null,"permalink":"/open-source/pairdrop-deployment/","section":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","summary":"","title":"PairDrop 部署指南","type":"open-source"},{"content":" GitHub 使用指南 # GitHub 是全球最大的代码托管平台，也是开源协作的核心工具。本指南将从零开始，帮助你掌握 GitHub 的核心功能和最佳实践。\n1. GitHub 基础概念 # 1.1 什么是 GitHub？ # GitHub 是基于 Git 的代码托管平台，提供：\n代码存储：安全地存储和管理代码 版本控制：追踪代码变更历史 协作开发：多人协作开发项目 开源社区：参与和贡献开源项目 1.2 核心术语 # 术语 说明 Repository (仓库) 存放项目代码的地方，类似项目文件夹 Commit (提交) 保存代码变更的快照 Branch (分支) 独立的开发线，用于并行开发 Pull Request (PR) 请求将代码合并到主分支 Fork 复制他人的仓库到自己的账户 Clone 将远程仓库复制到本地 Push 将本地代码推送到远程仓库 Pull 从远程仓库拉取最新代码 2. 账户设置与初始化 # 2.1 创建 GitHub 账户 # 访问 GitHub.com 点击 \u0026ldquo;Sign up\u0026rdquo; 注册账户 填写用户名、邮箱和密码 验证邮箱地址 2.2 配置 SSH 密钥（推荐） # SSH 密钥让你无需每次输入密码即可推送代码。\n生成 SSH 密钥：\nssh-keygen -t ed25519 -C \u0026#34;your_email@example.com\u0026#34; 添加密钥到 GitHub：\n复制公钥内容： cat ~/.ssh/id_ed25519.pub 在 GitHub 上添加： 进入 Settings → SSH and GPG keys 点击 \u0026ldquo;New SSH key\u0026rdquo; 粘贴公钥内容并保存 测试连接：\nssh -T git@github.com 2.3 配置 Git 用户信息 # git config --global user.name \u0026#34;你的用户名\u0026#34; git config --global user.email \u0026#34;your_email@example.com\u0026#34; 3. 创建和管理仓库 # 3.1 创建新仓库 # 通过网页创建：\n点击右上角 \u0026ldquo;+\u0026rdquo; → \u0026ldquo;New repository\u0026rdquo; 填写仓库名称（如 my-awesome-project） 选择公开或私有 可选：添加 README、.gitignore、License 点击 \u0026ldquo;Create repository\u0026rdquo; 通过命令行创建：\n# 初始化本地仓库 git init git add . git commit -m \u0026#34;Initial commit\u0026#34; # 添加远程仓库 git remote add origin git@github.com:username/repo-name.git git branch -M main git push -u origin main 3.2 克隆现有仓库 # # HTTPS 方式 git clone https://github.com/username/repo-name.git # SSH 方式（推荐） git clone git@github.com:username/repo-name.git 3.3 仓库设置 # 仓库描述：简要说明项目用途 仓库标签：添加主题标签（如 python, machine-learning） 默认分支：设置主分支名称（推荐 main） Wiki：启用项目文档 Issues：启用问题跟踪 Projects：启用项目管理看板 4. Git 基础操作 # 4.1 工作流程 # 工作区 → 暂存区 → 本地仓库 → 远程仓库 4.2 常用命令 # 查看状态：\ngit status 添加文件到暂存区：\n# 添加所有文件 git add . # 添加特定文件 git add filename.py # 添加所有 .py 文件 git add *.py 提交更改：\ngit commit -m \u0026#34;描述你的更改\u0026#34; 推送到远程：\n# 推送到当前分支 git push # 推送到指定分支 git push origin main # 首次推送并设置上游 git push -u origin main 拉取最新代码：\ngit pull 4.3 查看历史 # # 查看提交历史 git log # 查看简洁历史 git log --oneline # 查看图形化历史 git log --graph --oneline --all # 查看文件变更 git diff 5. Git 回退操作 # 5.1 撤销工作区修改（未提交） # 丢弃单个文件的修改：\n# 恢复文件到上次提交的状态 git checkout -- filename.py # 或使用 restore（推荐） git restore filename.py 丢弃所有修改：\n# 恢复所有文件 git checkout -- . # 或使用 restore（推荐） git restore . 5.2 撤销暂存区（已 add 未 commit） # 取消暂存单个文件：\n# 从暂存区移除，保留工作区修改 git reset HEAD filename.py # 或使用 restore（推荐） git restore --staged filename.py 取消暂存所有文件：\ngit reset HEAD # 或使用 restore（推荐） git restore --staged . 5.3 回退提交（已 commit） # 保留修改的回退（推荐）：\n# 回退到指定提交，修改保留在暂存区 git reset --soft HEAD~1 # 回退到指定提交，修改保留在工作区 git reset --mixed HEAD~1 # 默认模式 彻底回退（丢弃修改）：\n# 回退到指定提交，丢弃所有修改 git reset --hard HEAD~1 # 回退到指定 commit hash git reset --hard abc1234 5.4 安全回退（创建新提交撤销） # 使用 revert（推荐用于已推送的提交）：\n# 撤销最近一次提交，创建一个新的反向提交 git revert HEAD # 撤销指定提交 git revert abc1234 # 撤销多个提交 git revert HEAD~3..HEAD 5.5 回退对比 # 方式 使用场景 是否保留修改 是否改写历史 git restore 丢弃工作区修改 ❌ ❌ git restore --staged 取消暂存 ✅ ❌ git reset --soft 回退提交，保留修改在暂存区 ✅ ✅ git reset --mixed 回退提交，保留修改在工作区 ✅ ✅ git reset --hard 彻底回退，丢弃所有修改 ❌ ✅ git revert 安全回退，创建新提交 ✅ ❌ 5.6 回退已推送到远程的提交 # 场景 1：使用 revert（推荐）\n# 创建一个反向提交 git revert HEAD git push # 效果：历史记录保留，代码回退 # A → B → C → C\u0026#39;（C 的反向） 场景 2：使用 reset（谨慎使用）\n# 本地回退 git reset --hard HEAD~1 # 强制推送（会改写远程历史） git push --force # 或更安全的方式 git push --force-with-lease ⚠️ 警告：git push --force 会改写远程历史，可能影响其他协作者。仅在个人分支或确认无人使用时使用。\n5.7 找回误删的提交 # 查看所有操作记录：\n# 查看所有 HEAD 移动记录 git reflog # 输出示例： # abc1234 HEAD@{0}: reset: moving to HEAD~1 # def5678 HEAD@{1}: commit: add new feature 恢复到指定状态：\n# 根据 reflog 找到 commit hash git reset --hard def5678 6. 分支管理 # 6.1 创建和切换分支 # # 创建新分支 git branch feature-branch # 切换到分支 git checkout feature-branch # 创建并切换（推荐） git checkout -b feature-branch # 切换到主分支 git checkout main 6.2 合并分支 # # 切换到目标分支（如 main） git checkout main # 合并 feature-branch git merge feature-branch # 删除已合并的分支 git branch -d feature-branch 6.3 分支最佳实践 # main (主分支) └── develop (开发分支) ├── feature/user-auth (功能分支) ├── feature/payment (功能分支) └── hotfix/critical-bug (修复分支) 分支命名规范：\nfeature/功能描述：新功能开发 bugfix/问题描述：Bug 修复 hotfix/紧急问题：紧急修复 refactor/重构内容：代码重构 docs/文档内容：文档更新 7. Pull Request (PR) 工作流 # 7.1 Fork 工作流（贡献开源项目） # Fork 原仓库：点击 Fork 按钮复制到你的账户 克隆你的 Fork： git clone git@github.com:your-username/original-repo.git cd original-repo 添加上游仓库： git remote add upstream git@github.com:original-owner/original-repo.git 创建功能分支： git checkout -b feature/my-contribution 进行修改并提交： git add . git commit -m \u0026#34;Add new feature\u0026#34; git push origin feature/my-contribution 创建 Pull Request：\n在你的 Fork 页面点击 \u0026ldquo;Pull requests\u0026rdquo; 点击 \u0026ldquo;New pull request\u0026rdquo; 选择你的分支和目标分支 填写 PR 标题和描述 点击 \u0026ldquo;Create pull request\u0026rdquo; 同步上游更新：\ngit fetch upstream git checkout main git merge upstream/main git push origin main 7.2 PR 描述模板 # ## 变更说明 简要描述这个 PR 的目的和内容。 ## 变更类型 - [ ] 新功能 - [ ] Bug 修复 - [ ] 性能优化 - [ ] 文档更新 - [ ] 代码重构 ## 测试情况 - [ ] 已在本地测试通过 - [ ] 已添加单元测试 - [ ] 已更新相关文档 ## 相关 Issue Closes #123 ## 截图（如适用） [上传截图] ## 检查清单 - [ ] 代码遵循项目规范 - [ ] 已通过所有测试 - [ ] 已更新文档 8. Issues 管理 # 8.1 创建 Issue # 进入仓库的 \u0026ldquo;Issues\u0026rdquo; 标签页 点击 \u0026ldquo;New issue\u0026rdquo; 填写标题和详细描述 选择标签（如 bug, enhancement, documentation） 分配给相关人员（可选） 点击 \u0026ldquo;Submit new issue\u0026rdquo; 8.2 Issue 模板 # Bug 报告模板：\n## Bug 描述 清晰简洁地描述 bug 是什么。 ## 复现步骤 1. 进入 \u0026#39;...\u0026#39; 2. 点击 \u0026#39;....\u0026#39; 3. 滚动到 \u0026#39;....\u0026#39; 4. 看到错误 ## 期望行为 清晰描述你期望发生什么。 ## 实际行为 清晰描述实际发生了什么。 ## 环境信息 - OS: [例如 Windows 11] - 浏览器: [例如 Chrome 120] - 版本: [例如 v1.2.3] ## 截图 如果适用，添加截图来帮助解释问题。 ## 附加信息 添加任何其他关于问题的信息。 功能请求模板：\n## 功能描述 清晰简洁地描述你想要的功能。 ## 问题背景 描述这个功能解决的问题。 ## 期望解决方案 详细描述你希望如何实现这个功能。 ## 替代方案 描述你考虑过的任何替代解决方案或功能。 ## 附加信息 添加任何其他关于功能请求的信息。 8.3 Issue 标签管理 # 常用标签：\n标签 用途 bug Bug 报告 enhancement 功能增强 documentation 文档相关 good first issue 适合新手 help wanted 需要帮助 priority: high 高优先级 wontfix 不会修复 9. GitHub Actions 自动化 # 9.1 创建工作流 # 在 .github/workflows/ 目录下创建 YAML 文件：\nname: CI on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python uses: actions/setup-python@v4 with: python-version: \u0026#39;3.9\u0026#39; - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt - name: Run tests run: | pytest 9.2 常用 Actions # 自动部署：\n- name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist 发布到 PyPI：\n- name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: password: ${{ secrets.PYPI_API_TOKEN }} 10. GitHub Pages 静态网站 # 10.1 启用 GitHub Pages # 进入仓库 Settings 找到 \u0026ldquo;Pages\u0026rdquo; 部分 选择 Source（Branch 或 Workflow） 选择分支和目录（如 main 分支的 /docs 文件夹） 点击 Save 10.2 部署流程 # 使用 Actions 自动部署：\nname: Deploy to GitHub Pages on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: \u0026#39;18\u0026#39; - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Deploy uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist 11. 最佳实践 # 11.1 Commit 消息规范 # Conventional Commits 格式：\n\u0026lt;type\u0026gt;(\u0026lt;scope\u0026gt;): \u0026lt;subject\u0026gt; \u0026lt;body\u0026gt; \u0026lt;footer\u0026gt; 类型说明：\n类型 说明 示例 feat 新功能 feat(auth): add OAuth login fix Bug 修复 fix(api): resolve timeout issue docs 文档更新 docs(readme): update installation guide style 代码格式 style: format code with prettier refactor 重构 refactor(user): simplify validation logic test 测试 test(api): add unit tests for user module chore 构建/工具 chore: update dependencies 11.2 .gitignore 最佳实践 # Python 项目：\n# Python __pycache__/ *.py[cod] *$py.class *.so .Python venv/ env/ ENV/ # IDE .vscode/ .idea/ *.swp *.swo # OS .DS_Store Thumbs.db # Project specific config.local.yaml secrets.yaml Node.js 项目：\n# Dependencies node_modules/ npm-debug.log* yarn-debug.log* yarn-error.log* # Build dist/ build/ *.tgz # Environment .env .env.local .env.*.local # IDE .vscode/ .idea/ 11.3 安全最佳实践 # 不要提交敏感信息：\nAPI 密钥 数据库密码 私钥文件 个人信息 使用环境变量：\n# .github/workflows/deploy.yml env: API_KEY: ${{ secrets.API_KEY }} 使用 Secrets：\nSettings → Secrets and variables → Actions 点击 \u0026ldquo;New repository secret\u0026rdquo; 添加名称和值 11.4 README 编写规范 # 标准 README 结构：\n# 项目名称 简短的项目描述 ## 功能特性 - 功能 1 - 功能 2 - 功能 3 ## 安装 ```bash npm install my-project 使用 # const myProject = require(\u0026#39;my-project\u0026#39;); myProject.doSomething(); 配置 # 参数 说明 默认值 apiKey API 密钥 null timeout 超时时间 5000 贡献指南 # 欢迎贡献！请查看 CONTRIBUTING.md\n许可证 # MIT License\n--- ## 12. 高级功能 ### 12.1 GitHub Codespaces 云端开发环境，无需本地配置。 **使用步骤：** 1. 点击仓库的 \u0026#34;Code\u0026#34; 按钮 2. 选择 \u0026#34;Codespaces\u0026#34; 标签 3. 点击 \u0026#34;Create codespace on main\u0026#34; 4. 等待环境创建完成 ### 12.2 GitHub Copilot AI 编程助手，提供智能代码补全。 **启用步骤：** 1. 进入 GitHub Settings 2. 找到 \u0026#34;Copilot\u0026#34; 部分 3. 点击 \u0026#34;Start trial\u0026#34; 或订阅 4. 安装 VS Code 扩展 ### 12.3 GitHub Projects 项目管理工具，支持看板和表格视图。 **创建项目：** 1. 进入仓库的 \u0026#34;Projects\u0026#34; 标签页 2. 点击 \u0026#34;New project\u0026#34; 3. 选择模板（Board 或 Table） 4. 添加列和任务 --- ## 13. 故障排查 ### 13.1 常见问题 **问题 1：推送时提示权限被拒绝** ```bash # 解决方案：检查远程仓库 URL git remote -v # 如果是 HTTPS，改为 SSH git remote set-url origin git@github.com:username/repo.git 问题 2：合并冲突\n# 解决方案：手动解决冲突后 git add . git commit -m \u0026#34;Resolve merge conflict\u0026#34; git push 问题 3：无法拉取最新代码\n# 解决方案：强制更新 git fetch --all git reset --hard origin/main 13.2 调试技巧 # 查看远程仓库信息：\ngit remote -v 查看分支跟踪关系：\ngit branch -vv 清理无用分支：\ngit remote prune origin 14. 资源链接 # 官方文档 # GitHub 官方文档 Git 官方文档 学习资源 # GitHub Skills GitHub Learning Lab Learn Git Branching 工具推荐 # GitHub Desktop - 图形化 Git 客户端 GitKraken - 可视化 Git 工具 SourceTree - 免费 Git 客户端 15. 总结 # GitHub 是现代软件开发不可或缺的工具。掌握以下核心技能：\n✅ 基础操作：创建仓库、克隆、提交、推送 ✅ 分支管理：创建、切换、合并分支 ✅ 协作开发：Pull Request、Code Review ✅ 问题跟踪：Issues、标签、里程碑 ✅ 自动化：GitHub Actions、CI/CD ✅ 最佳实践：Commit 规范、安全、文档\n持续实践和探索，你将更高效地使用 GitHub 进行开发和协作！\n最后更新：2026-02-09\n","date":"2026-02-09","externalUrl":null,"permalink":"/open-source/github_guide/","section":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","summary":"","title":"GitHub 使用指南","type":"open-source"},{"content":" Hugo 网站部署指南 # Hugo 是一个快速、灵活的静态网站生成器，适合部署在各种平台上。从本地开发到上线，部署 Hugo 网站可以选择多种方式，具体步骤如下：\n前置条件 # 在部署前，请确保已完成以下准备工作：\nHugo 安装：\n请参考 Hugo 官方文档 安装 Hugo，确保您的版本支持当前项目。 完成本地开发：\n所有文章已完成，并存储在 content 文件夹中。 本地预览无误（使用 hugo server 进行预览）。 版本控制：\n使用 Git 或其他版本控制工具管理项目。 选择部署平台：\n部署 Hugo 静态网站的常见平台包括 GitHub Pages、Vercel、Netlify 等，请根据需要选择。 部署流程 # 1. 使用 Git 管理代码 # 在本地代码目录下初始化 Git 仓库，并确保代码已上传至远程：\n# 初始化 Git 仓库 git init # 添加所有文件并提交 git add . git commit -m \u0026#34;Initial commit\u0026#34; # 关联远程仓库 git remote add origin \u0026lt;你的远程仓库地址\u0026gt; git push -u origin main 2. 生成静态文件 # 运行以下命令生成 Hugo 项目静态文件：\n# 运行 Hugo 构建器，在 /public 文件夹输出静态文件 hugo 生成的 /public 文件夹即为 Hugo 的静态文件输出目录。\n3. 部署到不同平台 # 方法一：部署至 GitHub Pages # 创建 GitHub 仓库：\n登录 GitHub，新建一个仓库（例如 username.github.io）。 切换到 public 目录部署： Hugo 的 /public 文件夹生成了所有静态网站文件，需部署到仓库：\ncd public git init git add . git commit -m \u0026#34;Deploy Hugo Website\u0026#34; git branch -M main git remote add origin https://github.com/\u0026lt;username\u0026gt;/\u0026lt;username\u0026gt;.github.io.git git push -u origin main 启用 GitHub Pages：\n打开 GitHub 仓库设置，在 Pages（GitHub Pages）部分选择分支 main，并保存。 网站稍后将上线于 https://\u0026lt;username\u0026gt;.github.io。\n方法二：部署至 Netlify # 账号注册与项目创建：\n注册 Netlify 账号。 点击 “New Site From Git”，连接 GitHub 仓库。 设置部署配置：\n在部署设置中，填入构建命令： hugo 并指定发布目录： public 完成部署：\n确认无误后，Netlify 会自动检测项目，并运行构建，随后生成可用的网址。 方法三：部署至 Vercel # 账号注册与导入项目：\n注册 Vercel 账号。 新建项目，选择 Hugo 项目的 Git 仓库。 指定构建配置：\n在 “Build and Output Settings” 中，填写以下内容： Build Command： hugo Output Directory： public 完整部署：\n点击部署后，Vercel 将自动构建项目，并生成可访问的网站链接。 常见问题 # 1. 构建失败怎么办？ # 检查配置文件：确保 hugo.toml（或 config.yaml、config.json）的配置无误，特别是 baseURL。 查看日志：运行 hugo 命令时留意错误日志，并根据提示解决问题。 2. 部署后样式丢失？ # 确认部署平台是否正确处理 Hugo 的静态资源，例如 Netlify/Vercel 需要手动指定发布目录为 public。 3. 如何重新部署？ # 修改代码后，重复以上流程即可。 总结 # Hugo 是一个高效的静态网站生成器，支持的部署方式灵活多样。开发者可以根据项目需求和自己的喜好选择不同的平台。\n希望本指南能够帮助您顺利完成 Hugo 网站的部署！\n","date":"2026-02-07","externalUrl":null,"permalink":"/open-source/hugo_blog_stu/","section":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","summary":"","title":"Hugo_blog_stu","type":"open-source"},{"content":" ServerPackCreator 使用指南（泛用版） # ServerPackCreator 是一款强大的自动化工具，可帮助玩家快速创建 Minecraft 整合包的服务端版本。以下内容将以步骤为导向，帮助您通过该工具创建完美的服务端整合包。\n1. 前置准备（环境检查清单） # Java 版本确认（运行 ServerPackCreator 需要 Java 21，但生成的服务端可能需要其他版本如 Java 17）。 整合包基本信息收集： Minecraft 版本（如 1.20.1）。 模组加载器类型（Forge/Fabric/NeoForge/Quilt）。 加载器版本号（如 Forge 47.4.16）。 客户端整合包已正常运行（确保无损坏）。 2. 工具原理说明 # ServerPackCreator 是一款自动化工具，而非万能解决方案。以下是几点重要说明：\n自动扫描与排除功能： 它会自动扫描并尝试排除客户端模组。 人工校验的必要性： 无法 100% 准确识别所有客户端专属模组，最终仍需人工验证和调整。 3. 标准操作流程 # 3.1 生成阶段 # 选择整合包目录：选择包含 mods/、config/ 等文件夹的目录。 配置服务端参数： 内存分配（建议 -Xms4G -Xmx8G 起步）。 确认 Minecraft 版本和加载器版本。 设置额外包含目录（重要！）： scripts/（CraftTweaker 脚本）。 kubejs/（KubeJS 数据）。 defaultconfigs/。 自定义数据包文件夹（如 tacz/）。 生成服务器包。 3.2 人工审查阶段（关键！） # 必须审查以下客户端专属模组，并将其删除：\n模组类型 典型文件名关键词 处理方式 JEI 及其扩展 jei, jeresources, jeitweaker 删除 信息显示 jade, waila, theoneprobe 删除 地图类 journeymap, xaeros 删除 视觉优化 optifine, oculus, rubidium 删除 输入辅助 mousetweaks, controlling 删除 纯客户端功能 trashslot, itemscroller 删除 注意事项：\n某些模组如 JEI 有服务端兼容版本，例如 jei-1.20.1-forge-xxx.jar，应保留。 删除依赖特定客户端模组的扩展模组时可能引发崩溃（如 elementalcombat_jade 依赖 Jade）。 4. 故障排查速查表 # 错误现象 可能原因 解决方案 Attempted to load class ... for invalid dist DEDICATED_SERVER 客户端模组未删除 删除对应模组 requires xxx ... Currently, xxx is not installed 依赖模组缺失 安装缺失模组，或删除依赖它的模组 NoClassDefFoundError: mezz/jei/... JEI 扩展模组残留 删除所有 JEI 相关扩展 Initial heap size set to a larger value than the maximum heap size 内存参数配置错误 检查 -Xms 是否大于 -Xmx Error: Unable to access jarfile server.jar 下载失败 手动下载 server.jar 放入目录 启动后长时间无输出 世界生成中 等待 2-10 分钟 5. 通用最佳实践 # 5.1 渐进式测试法 # 首次启动：观察崩溃日志，记录所有客户端模组错误。 分批删除：每次删除一批客户端模组后重启测试。 保留清单：建立该整合包的“排除模组清单”供下次使用。 5.2 版本兼容性检查 # 确认模组加载器版本（如 Forge 47.4.16）。 检查 Java 版本要求（如 Minecraft 1.20.1 通常需要 Java 17）。 验证模组之间的交叉依赖关系。 5.3 配置文件管理 # 保留 config/ 和 defaultconfigs/ 文件夹的完整性。 检查 server.properties 是否需要预配置。 确认数据包文件夹（如 tacz/）已正确复制。 6. 进阶：制作可复用的排除清单 # 在 ServerPackCreator GUI 中配置 \u0026ldquo;Exclude Mods\u0026rdquo; 列表：\njei jeresources jeitweaker jecharacters jade journeymap xaeros optifine oculus rubidium mousetweaks controlling trashslot appleskin torohealth 7. 重要提醒 # ⚠️ ServerPackCreator 不是万能的\n它只能处理约 70-80% 的客户端模组识别，剩余的 20-30% 需要：\n根据崩溃日志人工判断。 了解各模组的功能定位。 多次迭代测试。 建议：首次处理某整合包时，预留 30-60 分钟的调试时间。\n案例学习：勇者之章3 # 问题 根本原因 泛化教训 forgeautofish 崩溃 纯客户端模组未过滤 自动钓鱼类模组必删 jecharacters 崩溃 JEI 拼音搜索，纯客户端 所有 JEI 扩展都要检查 elementalcombat_jade 崩溃 依赖 Jade 的扩展 删除主模组后须清理其扩展 JeiTweaker 崩溃 CraftTweaker 的 JEI 扩展 CT 扩展模组需单独检查 tacz/ 文件夹丢失 TACZ 枪包数据未保留 自定义资源文件需保留 ","date":"2026-02-07","externalUrl":null,"permalink":"/open-source/serverpackcreator_learn/","section":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","summary":"","title":"Serverpackcreator_learn","type":"open-source"},{"content":"","date":"2023-01-15","externalUrl":null,"permalink":"/write/","section":"⋅˚₊‧ ୨ thoughts index ୧ ‧₊˚ ⋅","summary":"","title":"⋅˚₊‧ ୨ thoughts index ୧ ‧₊˚ ⋅","type":"write"},{"content":"Tempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod. Labore ut ea duis dolor. Incididunt consectetur proident qui occaecat incididunt do nisi Lorem. Tempor do laborum elit laboris excepteur eiusmod do. Eiusmod nisi excepteur ut amet pariatur adipisicing Lorem.\nunordered list item 1 unordered list item 2 unordered list item 3 ordered list ordered list ordered list to do list to do list Tempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod. Labore ut ea duis dolor. Incididunt consectetur proident qui occaecat incididunt do nisi Lorem. Tempor do laborum elit laboris excepteur eiusmod do. Eiusmod nisi excepteur ut amet pariatur adipisicing Lorem.\nTempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod.\n","date":"2023-01-15","externalUrl":null,"permalink":"/write/test/","section":"⋅˚₊‧ ୨ thoughts index ୧ ‧₊˚ ⋅","summary":"","title":"example1","type":"write"},{"content":"Tempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod. Labore ut ea duis dolor. Incididunt consectetur proident qui occaecat incididunt do nisi Lorem. Tempor do laborum elit laboris excepteur eiusmod do. Eiusmod nisi excepteur ut amet pariatur adipisicing Lorem.\nunordered list item 1 unordered list item 2 unordered list item 3 ordered list ordered list ordered list to do list to do list Tempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod. Labore ut ea duis dolor. Incididunt consectetur proident qui occaecat incididunt do nisi Lorem. Tempor do laborum elit laboris excepteur eiusmod do. Eiusmod nisi excepteur ut amet pariatur adipisicing Lorem.\nTempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod.\n","date":"2023-01-15","externalUrl":null,"permalink":"/write/test2/","section":"⋅˚₊‧ ୨ thoughts index ୧ ‧₊˚ ⋅","summary":"","title":"example2","type":"write"},{"content":"Tempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod. Labore ut ea duis dolor. Incididunt consectetur proident qui occaecat incididunt do nisi Lorem. Tempor do laborum elit laboris excepteur eiusmod do. Eiusmod nisi excepteur ut amet pariatur adipisicing Lorem.\nunordered list item 1 unordered list item 2 unordered list item 3 ordered list ordered list ordered list to do list to do list Tempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod. Labore ut ea duis dolor. Incididunt consectetur proident qui occaecat incididunt do nisi Lorem. Tempor do laborum elit laboris excepteur eiusmod do. Eiusmod nisi excepteur ut amet pariatur adipisicing Lorem.\nTempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod.\n","date":"2023-01-15","externalUrl":null,"permalink":"/open-source/test3/","section":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","summary":"","title":"example3","type":"open-source"},{"content":"Tempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod. Labore ut ea duis dolor. Incididunt consectetur proident qui occaecat incididunt do nisi Lorem. Tempor do laborum elit laboris excepteur eiusmod do. Eiusmod nisi excepteur ut amet pariatur adipisicing Lorem.\nunordered list item 1 unordered list item 2 unordered list item 3 ordered list ordered list ordered list to do list to do list Tempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod. Labore ut ea duis dolor. Incididunt consectetur proident qui occaecat incididunt do nisi Lorem. Tempor do laborum elit laboris excepteur eiusmod do. Eiusmod nisi excepteur ut amet pariatur adipisicing Lorem.\nTempor proident minim aliquip reprehenderit dolor et ad anim Lorem duis sint eiusmod.\n","date":"2023-01-15","externalUrl":null,"permalink":"/open-source/test4/","section":"⋅˚₊‧ ୨ contributions index ୧ ‧₊˚ ⋅","summary":"","title":"example4","type":"open-source"},{"content":"","date":"2023-01-15","externalUrl":null,"permalink":"/tags/write/","section":"Tags","summary":"","title":"Write","type":"tags"},{"content":"","externalUrl":null,"permalink":"/categories/","section":"Categories","summary":"","title":"Categories","type":"categories"},{"content":"","externalUrl":null,"permalink":"/me/","section":"","summary":"","title":"me","type":"page"}]