configure-git-webserver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configure Git Webserver

配置Git Web服务器

Overview

概述

This skill provides guidance for setting up a Git-based web deployment system where pushing to a Git repository automatically deploys content to a web server. The typical workflow involves creating a bare Git repository, configuring a post-receive hook to deploy content, and running a web server to serve the deployed files.

本技能提供了基于Git的Web部署系统搭建指南，向Git仓库推送代码时会自动将内容部署到Web服务器。典型工作流包括创建裸Git仓库、配置post-receive钩子以实现部署自动化，以及启动Web服务器来托管部署后的文件。

Approach

实施步骤

Component Identification

组件识别

Before implementation, identify all required components:

Bare Git repository - The central repository that receives pushes
Web content directory - Where deployed files are served from
Post-receive hook - Automates deployment on push
Web server - Serves the deployed content
User access - Permissions for users to push to the repository

在实施前，先确认所有所需组件：

裸Git仓库 - 接收代码推送的中央仓库
Web内容目录 - 部署后的文件托管目录
Post-receive钩子 - 推送时自动触发部署
Web服务器 - 托管部署后的内容
用户权限 - 用户向仓库推送代码的权限配置

Implementation Sequence

实施顺序

Execute tasks in dependency order:

Create the bare Git repository first (other components depend on its location)
Create the web content directory
Create and configure the post-receive hook (depends on both repository and web directory)
Start the web server (depends on web directory existing)
Configure user access as needed

按照依赖关系依次执行任务：

首先创建裸Git仓库（其他组件的配置依赖其位置）
创建Web内容目录
创建并配置post-receive钩子（依赖仓库和Web目录的位置）
启动Web服务器（依赖Web目录已存在）
根据需要配置用户权限

Post-Receive Hook Design

Post-receive钩子设计

The post-receive hook should:

Handle multiple branch names (both
```
master
```
and
```
main
```
for compatibility)
Use
```
git --work-tree
```
to checkout to the web directory
Be marked executable (
```
chmod +x
```
)
Include the proper shebang (
```
#!/bin/bash
```
)

Example hook structure:

bash

#!/bin/bash
while read oldrev newrev ref
do
    branch=$(echo $ref | cut -d/ -f3)
    if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
        git --work-tree=/path/to/web/dir --git-dir=/path/to/repo checkout -f $branch
    fi
done

Post-receive钩子应满足以下要求：

支持多分支名称（兼容
```
master
```
和
```
main
```
分支）
使用
```
git --work-tree
```
将代码检出到Web目录
标记为可执行（
```
chmod +x
```
）
包含正确的shebang头（
```
#!/bin/bash
```
）

示例钩子结构：

bash

#!/bin/bash
while read oldrev newrev ref
do
    branch=$(echo $ref | cut -d/ -f3)
    if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
        git --work-tree=/path/to/web/dir --git-dir=/path/to/repo checkout -f $branch
    fi
done

Web Server Options

Web服务器选项

Consider available options based on environment:

```
python3 -m http.server
```
- Simple, usually available, single-threaded
```
nginx
```
- Production-ready, requires installation
```
node http-server
```
- Requires Node.js
```
busybox httpd
```
- Lightweight, often available in minimal environments

根据运行环境选择合适的Web服务器：

```
python3 -m http.server
```
- 简单易用，通常默认已安装，但为单线程
```
nginx
```
- 生产环境就绪，需单独安装
```
node http-server
```
- 依赖Node.js环境
```
busybox httpd
```
- 轻量级，常用于极简环境

Verification Strategies

验证策略

Component-Level Verification

组件级验证

Verify each component independently before testing the full workflow:

Repository verification: Check that the bare repository exists and has correct structure
bash
```
ls -la /path/to/repo  # Should show HEAD, objects/, refs/, etc.
```
Hook verification: Confirm hook exists and is executable
bash
```
ls -la /path/to/repo/hooks/post-receive
```

Web server verification: Confirm server is running and listening

bash

ss -tlnp | grep :PORT  # or netstat -tlnp, or ps aux | grep server

在测试完整工作流前，先独立验证每个组件：

仓库验证：检查裸Git仓库是否存在且结构正确

bash

ls -la /path/to/repo  # 应显示HEAD、objects/、refs/等目录和文件

钩子验证：确认钩子文件存在且可执行
bash
```
ls -la /path/to/repo/hooks/post-receive
```

Web服务器验证：确认服务器已启动并在监听端口

bash

ss -tlnp | grep :PORT  # 或使用netstat -tlnp，或ps aux | grep server

End-to-End Testing

端到端测试

Test the complete workflow:

Clone the repository (use local path for initial testing)
Create a test file and commit
Push to the repository
Verify the file appears in the web directory
Verify the file is accessible via HTTP

测试完整工作流：

克隆仓库（初始测试可使用本地路径）
创建测试文件并提交
推送代码到仓库
验证测试文件已出现在Web内容目录
验证通过HTTP可访问该文件

Pre-Check Available Commands

预检查可用命令

Before using system commands, verify availability to reduce trial-and-error:

bash

command -v netstat || command -v ss  # Network status
command -v systemctl || command -v service  # Service management

在执行系统命令前，先验证命令是否可用以减少试错：

bash

command -v netstat || command -v ss  # 网络状态查看命令
command -v systemctl || command -v service  # 服务管理命令

Common Pitfalls

常见问题

Persistence Issues

持久性问题

Problem: Background processes (like

python3 -m http.server &

) do not survive system restarts.

Mitigation: For production use, create a systemd service or use a process manager. For testing purposes, background processes are acceptable but document the limitation.

问题：后台进程（如

python3 -m http.server &

）在系统重启后无法存活。

解决方法：生产环境中，创建systemd服务或使用进程管理器管理。测试环境中可使用后台进程，但需注明该限制。

Permission Issues

权限问题

Problem: Users cannot push to the repository or the hook cannot write to the web directory.

Mitigation:

Verify repository ownership and permissions
Ensure the user running the hook has write access to the web directory
Check that the hook itself is executable

问题：用户无法向仓库推送代码，或钩子无法写入Web目录。

解决方法：

验证仓库的所有权和权限设置
确保运行钩子的用户拥有Web目录的写入权限
确认钩子文件本身已设置为可执行

Branch Name Handling

分支名称兼容问题

Problem: Hook only handles

master

but user pushes to

main

(or vice versa).

Mitigation: Handle both common default branch names in the hook logic.

问题：钩子仅处理

master

分支，但用户推送到

main

分支（反之亦然）。

解决方法：在钩子逻辑中同时兼容这两种常见的默认分支名称。

Testing Methodology

测试方法问题

Problem: Testing with local paths (

/git/server

) may pass but SSH-based access (

user@server:/git/server

) may fail.

Mitigation: If SSH access is required, verify SSH configuration and user access separately from the Git/web functionality.

问题：使用本地路径（

/git/server

）测试通过，但基于SSH的访问（

user@server:/git/server

）失败。

解决方法：若需要SSH访问，需单独验证SSH配置和用户权限，与Git/Web功能的验证分开进行。

Error Handling in Hooks

钩子错误无反馈

Problem: Hook failures are silent, making debugging difficult.

Mitigation: Add error output and logging to hooks:

bash

exec 2>&1  # Redirect stderr to stdout
set -e     # Exit on error

问题：钩子执行失败时无提示，调试困难。

解决方法：在钩子中添加错误输出和日志记录：

bash

exec 2>&1  # 将标准错误重定向到标准输出
set -e     # 遇到错误时立即退出

Single-Threaded Web Servers

单线程Web服务器限制

Problem: Simple web servers like

python3 -m http.server

are single-threaded and unsuitable for concurrent access.

Mitigation: Document this limitation. For production, use a proper web server like nginx.

问题：像

python3 -m http.server

这类简单Web服务器为单线程，不适合并发访问场景。

解决方法：注明该限制。生产环境中使用nginx等专业Web服务器。

Task Breakdown Guidance

任务拆分指南

Avoid excessive granularity in task tracking. Group related operations:

Good: "Set up bare Git repository with post-receive hook"
Avoid: Separate tasks for "create directory", "run git init", "create hook file", "make hook executable"

Focus task tracking on logical milestones rather than individual commands.

避免过度细化任务跟踪，将相关操作分组：

推荐：“搭建带post-receive钩子的裸Git仓库”
避免：将“创建目录”、“执行git init”、“创建钩子文件”、“设置钩子可执行”拆分为单独任务

任务跟踪应聚焦于逻辑里程碑而非单个命令。