Forem: 赵文博

It’s been a while since my last post. I finally built my first agent skill.

赵文博 — Fri, 06 Mar 2026 06:49:10 +0000

Requirement Clarifier

This skill is for requirement elicitation and clarification.

Goal

Identify unclear or missing parts in the user's request.
Ask focused follow-up questions step by step.
Produce a complete requirement markdown document.

When to Use

Use this skill when the user:

Provides only a rough idea without complete details.
Requests implementation but the scope is still vague.
Needs a structured requirement document before execution.

Required Document Structure

The final markdown document MUST contain these sections:

Background
Requirement Details
Examples
Terminology
Edge Conditions
Notes and Risks

Workflow

Follow this exact sequence.

Mode 1: Clarification Mode (Default)

When this skill is triggered, ALWAYS start in clarification mode.

The first response MUST contain:

A concise understanding summary based on the user's raw request.
A six-section skeleton with placeholders ([To be confirmed], [Information missing, need clarification]).
A numbered follow-up question list.

Do not output a full completed requirement document in this mode.

Step 1: Build Initial Skeleton

Based on the user's original message, create only the six-section skeleton.

Then ask:

This is my understanding based on your original request. Please confirm whether it is correct. If something is incorrect, please indicate which parts need to be modified. I will first enter clarification mode instead of generating the final document.

Step 2: Clarification Loop (Mandatory)

From the skeleton and the user's replies, identify all ambiguous or uncertain points and ask targeted follow-up questions.

Rules for questions:

Ask only high-value questions that reduce implementation ambiguity.
Prefer specific choices instead of open-ended questions.
Group related points, but keep each question easy to answer.
Each round should normally ask 3–7 questions (unless only 1–2 critical gaps remain).

After each user reply:

Update the internal draft.
Re-check for remaining uncertainty.
Continue asking until all critical ambiguity is removed.

Mode 2: Document Output Mode (After Confirmation)

Generate the full requirement markdown document ONLY when one of the following is true:

The user explicitly asks for the final document (e.g., "generate the final document", "output the complete requirement document").
The stop criteria are met and the user confirms no further changes are needed.

Stop Criteria

Stop asking questions only when all of the following are true:

The scope is explicit.
Inputs and outputs are explicit.
Edge or critical conditions are explicit.
Risks and constraints are explicit.
No section contains unresolved placeholder tags.

Output Rules

The default output is clarification Q&A, not the final document.
During clarification mode, output: Current Understanding Summary + Draft Skeleton + Follow-up Questions.
Keep wording precise and implementation-friendly.
Do not start coding in this skill; focus only on requirement clarity.
MUST NOT generate a complete final requirement document in the first response if key information is missing.

Final Output Template


markdown
# Requirement Document

## Background
...

## Requirement Details
...

## Examples
...

## Terminology
...

## Edge Conditions
...

## Notes and Risks
...

First try with OpenCode (Windows): finished the task while I played a game

赵文博 — Sun, 22 Feb 2026 16:35:12 +0000

Installation

E:\\ai-tools>curl -fsSL https://opencode.ai/install | bash

After installation, it looks like this:

Set the environment variable as prompted

My install path is: C:\\Users\\m1501\\.opencode\\bin

In CMD it becomes:

Run /models to pick a model. I tried using my existing ChatGPT Plus.
Install the code plugin

I tried many approaches on Windows, and this one worked.

This plugin upgrades OpenCode into a “multi-AI team”. Installation depends on your subscription.

First, confirm your subscription (used for configuration):

Claude Pro/Max: use -claude=yes or -claude=max20 (max20 is advanced mode).

ChatGPT Plus: use -chatgpt=yes.

Gemini: use -gemini=yes.

If you don’t have it, use no.

Install Bun (required by Oh My if you don’t have it):
curl -fsSL https://bun.sh/install | bash
Restart the terminal.

One-click install Oh My OpenCode:
bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=yes --gemini=yes
Replace the flags based on what you have. For example, only Claude:

bash bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no

If Bun has issues, use npx (requires Node.js):

bash npx oh-my-opencode install --no-tui --claude=yes ...

Verify:
cat ~/.config/opencode/opencode.json | grep "oh-my-opencode"
If you see the plugin name, installation succeeded.

Complete authentication (if you use paid models):

Run opencode auth login, choose a provider, then complete OAuth login in the browser.

For Gemini/ChatGPT, you may need an extra plugin (for example opencode-antigravity-auth). Add it to the plugin array in opencode.json.

At this point, my OpenCode configuration was basically done.

Then I tried running it in IntelliJ IDEA:

I wrote my requirements as a document for it. While I played a game of LoL, it finished everything.

That’s insane.

References

Java dominates China. What backend are YOU using?

赵文博 — Sun, 22 Feb 2026 09:04:40 +0000

Hey everyone 👋,

I’m a developer based in China. Over here, Java (especially Spring Boot) is the absolute king of backend development. It’s the default choice for almost everything, from massive tech giants to traditional enterprises. The talent pool and ecosystem are entirely built around it.

However, browsing global platforms like this one, I notice the conversation is completely different. I see a huge mix of Node.js, Python, Go, Rust, and C#, while Java doesn't seem to get as much of the spotlight among indie hackers and newer startups.

This stark contrast makes me really curious about the global landscape! So I'd love to ask:

What is your primary backend language/framework right now?
Why did you choose it over others? (Dev speed, raw performance, ecosystem, etc.)
What kind of environment are you building for? (Indie project, early-stage startup, or large enterprise?)

Looking forward to hearing about your stacks. Let's discuss! 🚀

Mastering CAP & BASE Theory with Gemini: From Distributed Principles to Nacos & Redis Reality

赵文博 — Fri, 20 Feb 2026 16:12:01 +0000

Core concepts

The CAP theorem (also known as Brewer’s Theorem) is a cornerstone for understanding distributed system design. It states that a distributed system cannot perfectly guarantee all three of the following properties at the same time:

Consistency (C): All nodes see the same data at the same time. For example, checking inventory at any branch returns exactly the same result.
Availability (A): Every request receives a response (success or failure), meaning the system is always “online”.
Partition Tolerance (P): The system continues to operate even when network failures split nodes into isolated groups (a partition).

In real networks, partitions (P) are inevitable, so a distributed system typically must trade off between CP and AP.

CP mode

In a CP system, if the network fails, the system chooses to stop serving requests in order to keep data strictly consistent across nodes.

Idea: It is better to return no result than to return incorrect or stale data.
Example: Bank transfers. If two servers are disconnected, the system must lock the account to prevent withdrawing money in two places and corrupting the data.
Cost: The system becomes unavailable during the fault.

AP mode

In an AP system, even if the network is partitioned, the system still prioritizes responding to requests.

Idea: Data might not be the latest, or different users might see different results, but users can still use the service.
Example: Social media likes. If you like a photo during a network partition, your friend might see it a few seconds later. That is acceptable. What matters is that the service does not become unusable because of network instability.
Cost: Sacrifices immediate consistency.

Case study: Nacos CP vs AP

1. Ephemeral instances vs persistent instances

This is the key logic behind how Nacos differentiates AP and CP:

AP mode (default): Used for ephemeral instances (Ephemeral Nodes). After registration, instances keep a heartbeat with the server. During a partition, Nacos prioritizes service availability, and short-term inconsistency is acceptable. This uses Nacos’s Distro protocol.
CP mode: Used for persistent instances (Persistent Nodes). Instance metadata is persisted to disk and requires strong consistency across nodes. If consensus cannot be reached due to a network failure, the system sacrifices availability. This uses a consensus protocol based on the Raft algorithm.

2. Why does Nacos support both?

This maps back to the trade-off question:

Service discovery usually leans toward AP. If network jitter makes the registry unavailable, all microservices may fail. That impact is too large. Small delays can often be masked by client retries.
Configuration management can lean toward CP. If a critical database password or rate-limit setting changes, it is often desirable for all nodes to immediately and consistently receive the exact latest value.

BASE theory

Once you understand the CAP trade-off between Consistency (C) and Availability (A), BASE theory can be viewed as a practical compromise for distributed systems.

The core idea is: since strong consistency is hard to achieve, we accept a more flexible approach so the system remains usable most of the time.

BASE is an acronym for:

Basically Available (BA): During failures, the system may lose some availability, but should not completely crash. For example, a page that normally loads in 0.1 seconds might take 2 seconds, or some non-core functionality may be temporarily disabled to protect core services.
Soft State (S): The system’s data is allowed to be in an intermediate state. Replication between nodes may be delayed, and this is considered acceptable for overall availability.
Eventually Consistent (E): The most important point. The system does not require data to be consistent at all times, but it guarantees that after some time, all replicas will converge to the same final state.

Case study: Redis Cluster

Redis Cluster (cluster mode) is generally designed to be AP (Availability + Partition Tolerance).

BASE in practice in Redis Cluster

Redis Cluster does not pursue strong consistency. Instead, it achieves eventual consistency via:

Basically Available (BA): Redis Cluster splits data into 16,384 hash slots. Even if a small number of nodes go down, the cluster can continue serving as long as most slots remain covered.
Soft State (S): After a master writes data, it returns success to the client immediately, then replicates to slaves asynchronously. This implies the master and slaves can be inconsistent at any given moment.
Eventually Consistent (E): Under normal conditions, slaves catch up with the master within milliseconds.

Why Redis Cluster is not strongly consistent

Consider this scenario:

Step 1: You write set key1 value1 to master node A.
Step 2: Node A writes to memory and immediately replies “OK”.
Step 3: Before A replicates the data to slave A1, A suddenly loses power and goes down.
Step 4: The cluster promotes slave A1 to become the new master.
Result: The value1 you just wrote is lost.

Build a Web Product from 0 to 1 (2): Documentation and Tech Stack Choices

赵文博 — Mon, 16 Feb 2026 13:03:27 +0000

Last time, we talked about how to clarify requirements and turn a vague idea into something concrete. That is the first step.
But as someone asked in the comments: “Ideas and execution are two different things. What if things change once you actually build it?”
That is true. In real execution, you will always spot logical gaps, or suddenly come up with a better idea. So requirement refinement is always work in progress.

1. From “minimal” to “richer”: how requirements become more complex

In the very first version, I only thought about the simplest model:

Project → Requirements → Progress

I felt that was enough. If it runs, it is fine. But once I started coding, I realized it was far from enough.

Since this is my own knowledge base / management system, why not collect other scattered needs as well? For example:

Link and document collection: where do useful references go?
Bug list: should I step into the same pit again next time?
Tech stack tracking: what versions does the project use? I need a “ledger”.

As a result, the final feature set became much larger than the initial draft.

2. Documentation: dealing with constant changes

Since requirements keep changing (which is normal for personal projects), documentation is necessary to avoid chaos.

At the moment, I use two main ways to record requirements: one high-level, one detailed.

2.1 Spreadsheet (a backlog, like a Notion requirement pool)

I keep a spreadsheet and put every requirement into a list. This lets me see, at a glance, how much work is still pending.

Requirement	Priority	Status	Description
Link collection	High	To do	Collect and manage project-related reference links and documents
Bug tracking	High	To do	Record and track issues found during development
Project management	High	To do	Manage project basics, progress, and milestones
Tech stack management	Medium	To do	Record and maintain the technologies and versions used by the project

Even for a personal project, I strongly recommend keeping the status up to date. Seeing “To do” become “Done” is one of the best sources of motivation.

2.2 Feature details (my “personal PRD”)

This is basically what product managers call a PRD. But since I am the product manager for myself, I do not need to make it overly formal.

I usually follow an outline like this. In practice, I merge requirement notes and development notes into one document to keep things simple:

Background: Why do I want to build this? What problem does it solve?
References: How do others do it? (Screenshots + feature notes.)
Key points: What should the feature look like?
Roles and permissions: Who can view and who can edit?
Database entity design: This is development-oriented, but thinking about schema early saves a lot of detours later.

The biggest benefit of documentation is that it prevents forgetting and reduces mess.

For example, while designing the “project management” module, I suddenly realized a team lead permission needed adjustment. If I only keep it in my head, I will forget it in a few days. But if I record it as a change in the feature details, it stays clear when I implement it.

3. Tech stack choices: not the most expensive, but the most practical

Honestly, I am not an experienced architect. Since this is my first serious small project, my principles are simple:

Use what I already know well
Make it run first

3.1 Core framework

Frontend + backend: Vue + Java (Spring Boot)
Architecture: the project is small, so I am not chasing microservices or distributed systems. A simple monolith is enough, and deployment is easier.

3.2 The storage dilemma (middleware)

For file storage, I spent some time thinking about options:

MinIO: self-hosted, data stays under my control. But I need to manage capacity and operations, and migration later can be painful.
Cloud OSS: very convenient, but it costs money. Also, there are many stories about unexpected billing or account abuse, which feels risky.

My conclusion: tech choices are not permanent. For now I will stay flexible and decide based on the actual deployment environment.

3.3 Database

MySQL: PostgreSQL is popular lately, and many people are switching. But for me, MySQL is the most familiar and the least risky.
Persistence layer: I chose MyBatis-Plus for speed and convenience.

3.4 Embracing AI

Since this is a new project, I want to try something new. I have already integrated Spring AI and combined it with the GLM-4.5 model.

The early test results look promising. Next, I plan to build some AI-assisted features.

4. Final thoughts: why “reinvent the wheel”?

If I used an off-the-shelf backend framework (for example, RuoYi), development would probably be twice as fast.

But I do not want to do that.

I want my first project to be something I built entirely by myself. That includes basic but tedious parts like login, registration, and permission/authentication. I did not rely on a ready-made framework for those (although I did read a lot and tried to implement reasonable security protections).

For a beginner’s first project:

Your framework does not need to be advanced, complex, or even the newest.
As long as it supports shipping the product, lets you run through the whole process, and helps you learn, it is a good tech stack choice.

Building My Own Web Product from 0 to 1 (1): Defining Requirements & Feature Analysis

赵文博 — Sat, 14 Feb 2026 14:50:36 +0000

TL;DR: I built and deployed a small website as an experiment. The key lesson was learning how to turn a vague idea into clear requirements, and then breaking features down into a simple, structured workflow.

Hi everyone. This is the first time I’m sharing some experience from when I deployed my own website independently.

Although my site has already been deployed online and officially registered, the features are still not complete, and it can only be accessed within China. So I cannot share a public link for you to visit yet.

Still, I can share my overall thinking, and I hope to learn and exchange ideas with more experienced builders.

Today’s topic is requirements analysis. When you have an idea, the most important step is turning that idea into concrete requirements. That’s not easy, which is why my first website was also an experimental project.

Starting from an idea: how can a startup or small team manage projects?

My first thought came from my interest in online note-taking and project management tools.

In my previous company, large teams often had their own project management systems. But those systems usually required filling in complicated forms and going through complex processes, which made them slow and inefficient.

Smaller companies often use tools like ZenTao, Jira, or Feishu. These tools are very general-purpose, but many features and workflows are unnecessary.

Some startups even rely on static documents or online documents to manage projects, but that approach is less automated and can easily become messy and hard to follow.

So I came up with the idea of building a simplified project management tool. This became the core feature of the website I designed. Only after having this idea could I start planning how to build the site.

Turning ideas into requirements: breaking down features

Turning an idea into requirements means breaking it down and refining it. There are many things to consider.

1) If other products are complicated, how can my system be simpler?

Remove unnecessary features.
Avoid complex configuration.

For example:

In ZenTao, building product modules and splitting into many team groups might be unnecessary for small companies.
In Jira, some configurations are very complex.

In many small companies, users might only care about:

Who the users are
What progress each person is making

2) How can the structure be clearer?

For progress reporting, project management can be structured as a simple model:

Project → Requirement → Progress

A minimal workflow could be:

Admins create projects.
Project owners or requirement owners create requirements.
Developers only need to report progress.

After defining the key requirements, you can then design the details, such as:

Entity/data model
API design
UI flow

Considering feasibility and risks

To be honest, I did not do enough in this area. This was just a trial project, but I still made some considerations.

Feasibility

The target customers were small businesses and startups, and their budgets are likely limited.

So I did not invest heavily in technology or resources.

Since small companies typically have fewer users, the performance requirements are also lower, which means I can save a lot of costs.

Risks

Users might be concerned about security, but I have not thought too much about that yet.

Closing thoughts

In the past, I was purely a technical engineer. This is just a bit of my common sense and experience.

I’m looking forward to discussing with everyone, and I would love to hear your opinions and suggestions.

Stress: Linux Stress Testing Tool

赵文博 — Fri, 13 Feb 2026 14:29:28 +0000

💡

This page summarizes how to install and use stress, plus common parameters and practical examples. It is meant as a quick reference for performance testing and bottleneck investigation.

Part 1: Overview

Basic Info

Tool name: stress
What it is: a Linux command-line stress testing tool that simulates high load by spawning worker processes.
What it can stress: CPU, memory (VM), disk I/O, and mixed workloads.
Source: CSDN: stress usage guide

Official docs and resources

Official documentation: (to be added)
GitHub repository: (to be added)

Part 2: How it works

Key features

CPU stress: spawn compute-heavy workers.
Memory stress: allocate, touch, and optionally keep memory.
I/O stress: call sync() to generate disk I/O pressure.
Mixed stress: combine CPU + memory + I/O to approximate real high-load scenarios.

Typical use cases:

Validating system stability under pressure
Comparing performance before and after tuning
Finding resource bottlenecks with monitoring tools (top, iostat, vmstat, etc.)

Core idea

stress launches multiple worker processes. Each worker type corresponds to a resource dimension:

CPU worker
VM (memory) worker
IO worker
HDD worker

A key parameter, --vm-stride, changes the memory write stride, which can affect Copy-On-Write behavior and shift CPU time between user space (us) and kernel space (sy).

Part 3: Installation and usage

Requirements

Linux (CentOS, Ubuntu, etc.)
Installation permissions (sudo)

Install on CentOS 7 (EPEL)

sudo yum install epel-release
sudo yum install stress
stress --version

Install on Ubuntu

sudo apt install stress
stress --version

Basic syntax

stress <options>

Part 4: Common options (with examples)

1) CPU stress

-c, --cpu N: start N CPU workers.
--backoff N: delay new forked processes by N microseconds before they start.

Example: start 4 CPU workers

stress -c 4

Monitoring tip: use top to observe per-process CPU usage.

2) Memory stress

-m, --vm N: start N memory workers.
--vm-bytes B: memory size per worker (for example 300M).

Example: 2 workers, 300MB each

stress -m 2 --vm-bytes 300M

Useful memory parameters:

--vm-keep: keep memory allocated (instead of allocate/free loops).

stress --vm 2 --vm-bytes 300M --vm-keep

--vm-hang N: sleep N seconds after allocation before freeing, then repeat.

stress --vm 2 --vm-bytes 300M --vm-hang 5

--vm-stride B: set memory write stride (can change COW frequency and CPU behavior).

stress --vm 2 --vm-bytes 500M --vm-stride 64

`--vm-stride` and CPU `us` vs `sy`

Small stride (for example 64 bytes): denser writes, more frequent COW, often higher user time (us).

stress --vm 2 --vm-bytes 500M --vm-stride 64

Large stride (for example 1M): less frequent COW, but may increase kernel memory-management overhead, often higher system time (sy).

stress --vm 2 --vm-bytes 500M --vm-stride 1M

Default stride: roughly 4096 bytes (4KB) if not specified.

stress --vm 2 --vm-bytes 500M

Quick reference:

`--vm-stride`	CPU tendency	Memory behavior	When to use
Small (e.g., 64)	Higher us	Frequent COW, dense writes	Simulate compute-heavy memory operations
Medium (e.g., 4K)	Balanced	Default-ish behavior	General memory stress testing
Large (e.g., 1M)	Higher sy	Less COW, more memory management overhead	Simulate kernel memory-management pressure

Notes:

COW (Copy-On-Write): pages are copied only when written.
us/sy: CPU time spent in user space vs kernel space.

3) I/O stress

-i, --io N: start N I/O workers. Each calls sync() to flush buffers to disk.

Example: start 4 I/O workers

stress -i 4

Monitoring tip (disk I/O):

iostat -x 2

Key metrics:

%util: device utilization, near 100% means saturated
r/s, w/s: reads/writes per second
rkB/s, wkB/s: throughput
await: average I/O latency
--hdd-bytes B: size of data written by HDD workers.

stress -i 1 --hdd-bytes 10M

4) Mixed workload

Example: CPU + memory + I/O + disk write

stress --cpu 4 --io 4 --vm 2 --vm-bytes 100M --vm-keep --hdd-bytes 10M

Meaning:

4 CPU workers
4 I/O workers
2 VM workers (100MB each) and keep the memory
write 10MB of data for disk pressure

5) Other handy options

-t, --timeout N: run for N seconds

stress -c 4 -t 60

-v, --verbose: verbose output

stress -c 4 -v

-q, --quiet: quiet mode

stress -c 4 -q

-n, --dry-run: print what would run, without actually stressing

stress -c 4 -n

Part 5: Monitoring recommendations

During stress tests, it is best to watch system metrics in parallel:

top: CPU, memory, and per-process usage
iostat: disk throughput and latency
vmstat: memory and overall system behavior

Practical tip: run the stress command and monitoring commands in separate terminals so you can compare load with metric changes.

Summary

Key takeaways

stress is a simple, fast way to create CPU, memory, and I/O pressure.
--vm-stride can significantly change memory write patterns and the CPU us/sy split.
Stress testing is most valuable when paired with monitoring.

Recommendation

Rating: ⭐⭐⭐⭐☆ (4/5)
Why: easy to use, parameters are straightforward, good for quickly building pressure scenarios.
Not ideal when: you need realistic end-to-end business traffic and request chains (use a dedicated load-testing platform/tool instead).

References

CSDN article

Docker Feature Overview

赵文博 — Fri, 13 Feb 2026 14:12:30 +0000

Basic Concepts

1) Container

A container is like a lightweight box that bundles everything an application needs to run.

Application code
Runtime (for example Java or Python)
Dependency libraries
Basic system tools

Compared with virtual machines, containers do not carry the overhead of a full guest operating system. They are smaller, start faster, and typically use resources more efficiently.

2) Image

An image is the template or blueprint used to create containers.

It is essentially a snapshot of a filesystem plus some metadata and configuration.
Images are built in layers.
When you run docker run <image>, Docker creates a container from that image and adds a writable layer on top.

3) Registry

A registry is where images are stored and distributed. Think of it as an “image warehouse”.

Public registries: Docker Hub, Aliyun Container Registry, and others.
Private registries: company-hosted registries for internal images.

Common operations:

Pull an image: docker pull <registry>/<image>:<tag>
Push an image: docker push <registry>/<image>:<tag>

How containers, images, and registries relate

Common Commands

# 1) Image management
docker images                     # list local images
docker pull nginx:latest          # pull an image from a registry
docker rmi nginx:latest           # remove a local image

# 2) Container management
docker run -d --name web nginx    # start an nginx container named "web" in background
docker ps                         # list running containers
docker ps -a                      # list all containers (including stopped ones)
docker stop web                   # stop the "web" container
docker start web                  # start a stopped container
docker rm web                     # remove a stopped container

# 3) Build an image
docker build -t myapp:1.0 .       # build an image from Dockerfile in current directory

# 4) Logs and monitoring
docker logs web                   # view container logs
docker stats web                  # realtime resource usage

Docker Networking

Docker creates several default networks:

bridge: default network (NAT + virtual bridge)
host: container shares the host network stack
none: no networking

Common commands:

# List networks
docker network ls

# Inspect a network
docker network inspect bridge

# Create a custom bridge network
docker network create --driver bridge my-net

# Start a container and attach it to the custom network
docker run -d --name db --network my-net mysql

# Connect an already-running container to a network
docker network connect my-net web

# Disconnect a container from a network
docker network disconnect my-net web

Why custom networks are useful:

Containers on the same user-defined network can reach each other by container name.
Better isolation between environments and services.

Inspecting Container Details

When you need detailed container configuration (port mappings, volumes, environment variables, etc.), use:

docker inspect web

The output is JSON. Useful fields include:

HostConfig.PortBindings: port mappings
Mounts: volume mounts
Config.Env: environment variables
NetworkSettings: networking

If you only want specific parts, combine with jq (or simple grep):

# Only port bindings
docker inspect web | jq '.[0].HostConfig.PortBindings'

# Only mounts
docker inspect web | jq '.[0].Mounts'

Tips

Layered images: every Dockerfile change usually creates a new layer. Layer caching makes builds faster.
Data persistence: in production, mount databases and logs to the host using volumes so data is not lost when containers are recreated.
Environment isolation: custom networks + private registries help isolate dev, test, and prod environments more cleanly.

A Comprehensive Guide to Nginx for Developers

赵文博 — Fri, 13 Feb 2026 13:43:47 +0000

👋

This is my first blog post on dev.to. I hope you enjoy it.

⚡

Nginx is a high-performance, event-driven, lightweight web server and reverse proxy. Thanks to its asynchronous and non-blocking architecture, it can handle a large number of concurrent connections with very low resource usage. Besides serving static assets efficiently, Nginx can route requests to backend services via proxy_pass and supports multiple load-balancing algorithms, such as round-robin, least connections, and IP hash. It is also commonly used for SSL termination, caching, separating static and dynamic traffic, and basic security hardening, which makes it a key traffic gateway in modern microservice and front-end/back-end separated architectures.

Basic Configuration

`http` vs `server` vs `location`

Context	What it does	Example
http	Global HTTP-level settings (timeouts, logs, compression, cache, etc.)	`http { proxy_read_timeout 300s; gzip on; }`
server	A virtual host (a “site”/service). Binds `listen` and `server_name`	`server { listen 80; server_name [example.com](http://example.com); … }`
location	URI prefix or regex matching rules. Defines how that kind of request is handled	`location /static/ { root /var/www; }`

Nesting structure

http {
  server {
    location { … }
    location { … }
  }
  server { … }
}

Responsibilities
- http: framework-level defaults, modules, overall behavior
- server: split traffic by domain/port
- location: serve static files, reverse proxy, URL rewrite, etc.

A minimal example (serving a SPA)

http {
  include       mime.types;
  default_type  application/octet-stream;
  sendfile      on;
  keepalive_timeout  65;

  server {
    listen       80;
    server_name  your.domain.com;    # or an IP

    # Point to your built dist directory
    root   /var/www/vue-app/dist;    # Linux path
    # Windows example: root C:/nginx/html/vue-app/dist;

    index  index.html;

    # Try static first; if not found, fall back to index.html (SPA History mode)
    location / {
      try_files $uri $uri/ /index.html;
    }

    # Optional: cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|svg|woff2?)$ {
      expires 30d;
      add_header Cache-Control "public";
    }

    # Error page
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
      root /var/www/vue-app/dist;
    }
  }
}

`include mime.types` and what it means

include loads an external file (or a set of files) into the current configuration context.

include mime.types; tells Nginx to load the file extension ↔ MIME type mapping table. That way, when Nginx serves static files like .html, .css, .js, .png, etc., it can automatically set the correct Content-Type header so browsers interpret assets correctly.

What `$uri` is (and why it matters for `try_files`)

$uri is a built-in Nginx variable. It comes from the request line’s URI part (without the query string) and is normalized by Nginx.

Example:

Browser requests: GET /foo/bar.html?abc=123 HTTP/1.1
Nginx sees $request_uri = /foo/bar.html?abc=123
Nginx strips the query part and normalizes the path, producing $uri = /foo/bar.html

In try_files $uri $uri/ /index.html;, Nginx checks the filesystem for the file or directory first. If nothing matches, it falls back to /index.html. This is why SPA routes still work on refresh under History mode.

Frontend-oriented settings (static site)

root points to the built dist directory
index is the default entry file
try_files enables SPA routing fallback (History mode)

Backend-oriented settings (reverse proxy)

listen defines the listening port
server_name defines the domain (or host) to match
location defines request matching rules and the upstream routing logic

Location matching order (common rules)

= exact match
^~ longest prefix match (and stop searching)
regex matches (~, ~*) in the order they appear (first match wins)
normal prefix match (longest)
if nothing matches, return 404

Reverse proxy request flow (high level)

Client sends a request

Browser or HTTP client connects to Nginx on the listening port and sends an HTTP request.
Nginx worker accepts the connection

In the event-driven model, a worker process accept()s the connection and parses it into an internal request object.
Pick an upstream server

If using upstream, Nginx selects a backend node based on the chosen algorithm. If proxy_pass points to a fixed host, it routes to that one.
Connect to upstream

Nginx creates a non-blocking socket and initiates a TCP connection, controlled by proxy_connect_timeout.
Forward the request

Nginx sends the request line, headers, and optional body to the upstream, controlled by proxy_send_timeout.
Read the response

Nginx reads the response status line, headers, and body from upstream, controlled by proxy_read_timeout, and streams or buffers it back to the client.
Reuse or close connections

With keepalive enabled, Nginx can reuse upstream connections to reduce handshake overhead.

Reverse Proxy

Feature	Forward Proxy	Reverse Proxy
Primary target	Client	Server (the website/service)
Traffic direction	Client → proxy → any external server	Client → proxy → internal backend servers
Typical use cases	Bypass restrictions, filtering, client-side caching	Load balancing, SSL termination, caching, hiding backend topology
Client configuration	Client must configure proxy	Client does not need to know (transparent)

Forward proxy: you explicitly choose a proxy to access external sites.
Reverse proxy: a proxy sits in front of your service and forwards requests to your backend.

Load Balancing

1) Minimal `upstream` (round-robin by default)

http {
  upstream backend {
    server 192.168.0.101:8080;
    server 192.168.0.102:8080;
    server 192.168.0.103:8080;
  }

  server {
    listen 80;
    server_name example.com;

    location / {
      proxy_pass http://backend;
    }
  }
}

Algorithm: round-robin
Pros: simplest setup

2) Weighted round-robin

http {
  upstream backend {
    server 192.168.0.101:8080 weight=5;
    server 192.168.0.102:8080 weight=3;
    server 192.168.0.103:8080 weight=2;
  }

  server {
    listen 80;

    location / {
      proxy_pass http://backend;
    }
  }
}

Larger weight means more traffic.
Useful when backend nodes have different capacity.

3) Least connections

http {
  upstream backend {
    least_conn;
    server 192.168.0.101:8080;
    server 192.168.0.102:8080;
    server 192.168.0.103:8080;
  }

  server {
    listen 80;

    location / {
      proxy_pass http://backend;
    }
  }
}

Routes new requests to the node with the fewest active connections.
Good when request duration varies a lot.

4) IP hash (session affinity)

http {
  upstream backend {
    ip_hash;
    server 192.168.0.101:8080;
    server 192.168.0.102:8080;
    server 192.168.0.103:8080;
  }

  server {
    listen 80;

    location / {
      proxy_pass http://backend;
    }
  }
}

Same client IP tends to hit the same backend.
Does not support weight.

5) URI hash (consistent hash)

http {
  upstream backend {
    hash $request_uri consistent;
    server 192.168.0.101:8080;
    server 192.168.0.102:8080;
    server 192.168.0.103:8080;
  }

  server {
    listen 80;

    location / {
      proxy_pass http://backend;
    }
  }
}

Hashes a variable (like $request_uri) to pick the node.
consistent reduces remapping when nodes change.

6) Basic failure handling

http {
  upstream backend {
    server 192.168.0.101:8080 max_fails=3 fail_timeout=30s;
    server 192.168.0.102:8080 max_fails=3 fail_timeout=30s;
    server 192.168.0.103:8080 max_fails=3 fail_timeout=30s;
  }
}

max_fails: failure threshold
fail_timeout: temporarily stop sending traffic to that node

Summary

Round-robin is the default and easiest.
Weighted round-robin helps with uneven node capacity.
Least connections is useful when requests have uneven duration.
IP hash and URI hash help with affinity.
max_fails and fail_timeout provide basic resilience.

Common Nginx Commands

# Test configuration syntax
nginx -t

# Start Nginx (if not running as a system service)
nginx
# Or specify a config file:
nginx -c /path/to/nginx.conf

# Reload gracefully
nginx -s reload

# Graceful stop
nginx -s quit

# Force stop
nginx -s stop

# Reopen log files (useful after log rotation)
nginx -s reopen

# Show version
nginx -v

# Show version and build options
nginx -V

# Show running processes
ps aux | grep nginx

# If managed by systemd
systemctl start nginx
systemctl stop nginx
systemctl reload nginx
systemctl status nginx

# (Optional) hot upgrade binary without dropping connections
kill -USR2 `cat /var/run/nginx.pid`

# Check listening ports
netstat -tulpn | grep nginx

Timeout Settings

1) Client-side timeouts

Directive	Default	Description
`client_header_timeout`	60s	Max time to receive request headers from the client. Returns 408 on timeout.
`client_body_timeout`	60s	Max time to receive the request body. Returns 408 on timeout.
`send_timeout`	60s	If the client does not read any response data within this time, Nginx closes the connection.

http {
  client_header_timeout 10s;
  client_body_timeout   30s;
  send_timeout          120s;
}

2) Reverse proxy (`proxy_pass`) timeouts

Directive	Default	Description
`proxy_connect_timeout`	60s	Timeout for establishing TCP connection to upstream (handshake). Returns 504 on timeout.
`proxy_send_timeout`	60s	Timeout for sending request to upstream (write). Returns 504 on timeout.
`proxy_read_timeout`	60s	Timeout for reading the response from upstream. Returns 504 on timeout.
`proxy_buffering`	on	When buffering is enabled, read timeout can behave differently. Turning it off can make streaming responses behave more predictably.

server {
  location /api/ {
    proxy_pass            http://backend;
    proxy_connect_timeout 120s;
    proxy_send_timeout    120s;
    proxy_read_timeout    300s;
    proxy_buffering       off;
  }
}

3) FastCGI / uWSGI / SCGI timeouts

Module	Directive	Default	Description
FastCGI	`fastcgi_connect_timeout`	60s	Connection timeout to FastCGI server
	`fastcgi_send_timeout`	60s	Send timeout to FastCGI server
	`fastcgi_read_timeout`	60s	Read timeout from FastCGI server
uWSGI	`uwsgi_connect_timeout`	60s	Connection timeout to uWSGI server
	`uwsgi_send_timeout`	60s	Send timeout to uWSGI server
	`uwsgi_read_timeout`	60s	Read timeout from uWSGI server
SCGI	`scgi_connect_timeout`	60s	Connection timeout to SCGI server
	`scgi_send_timeout`	60s	Send timeout to SCGI server
	`scgi_read_timeout`	60s	Read timeout from SCGI server

location ~ \.php$ {
  fastcgi_pass            unix:/run/php-fpm.sock;
  fastcgi_connect_timeout 30s;
  fastcgi_send_timeout    180s;
  fastcgi_read_timeout    180s;
}

4) Stream (TCP/UDP) proxy timeouts

stream {
  upstream mysql_up {
    server 127.0.0.1:3306;
  }

  server {
    listen 3307;
    proxy_pass            mysql_up;
    proxy_connect_timeout 10s;
    proxy_read_timeout    300s;
    proxy_send_timeout    300s;
  }
}

Keepalive

1) Client ↔ Nginx keepalive

Directive	Default	Description
`keepalive_timeout`	75s	Idle keepalive timeout after a request completes
`keepalive_requests`	100	Max requests per keepalive connection

http {
  keepalive_timeout  65s;
  keepalive_requests 200;
}

2) Nginx ↔ upstream keepalive (connection reuse)

http {
  upstream backend {
    server 192.168.0.101:8080;
    server 192.168.0.102:8080;
    keepalive 32;
  }

  server {
    listen 80;

    location / {
      proxy_pass http://backend;

      # Use HTTP/1.1 and clear Connection header for upstream keepalive
      proxy_http_version 1.1;
      proxy_set_header Connection "";
    }
  }
}

proxy_http_version 1.1: required for upstream keepalive
proxy_set_header Connection "": prevents Connection: close from breaking reuse

Forem: 赵文博

It’s been a while since my last post. I finally built my first agent skill.

Requirement Clarifier

Goal

When to Use

Required Document Structure

Workflow

Mode 1: Clarification Mode (Default)

Step 1: Build Initial Skeleton

Step 2: Clarification Loop (Mandatory)

Mode 2: Document Output Mode (After Confirmation)

Stop Criteria

Output Rules

Final Output Template

First try with OpenCode (Windows): finished the task while I played a game

Java dominates China. What backend are YOU using?

Mastering CAP & BASE Theory with Gemini: From Distributed Principles to Nacos & Redis Reality

Core concepts

CP mode

AP mode

Case study: Nacos CP vs AP

1. Ephemeral instances vs persistent instances

2. Why does Nacos support both?

BASE theory

Case study: Redis Cluster

BASE in practice in Redis Cluster

Why Redis Cluster is not strongly consistent

Build a Web Product from 0 to 1 (2): Documentation and Tech Stack Choices

1. From “minimal” to “richer”: how requirements become more complex

2. Documentation: dealing with constant changes

2.1 Spreadsheet (a backlog, like a Notion requirement pool)

2.2 Feature details (my “personal PRD”)

3. Tech stack choices: not the most expensive, but the most practical

3.1 Core framework

3.2 The storage dilemma (middleware)

3.3 Database

3.4 Embracing AI

4. Final thoughts: why “reinvent the wheel”?

Building My Own Web Product from 0 to 1 (1): Defining Requirements & Feature Analysis

Starting from an idea: how can a startup or small team manage projects?

Turning ideas into requirements: breaking down features

1) If other products are complicated, how can my system be simpler?

2) How can the structure be clearer?

Considering feasibility and risks

Feasibility

Risks

Closing thoughts

Stress: Linux Stress Testing Tool

Part 1: Overview

Basic Info

Official docs and resources

Part 2: How it works

Key features

Core idea

Part 3: Installation and usage

Requirements

Install on CentOS 7 (EPEL)

Install on Ubuntu

Basic syntax

Part 4: Common options (with examples)

1) CPU stress

2) Memory stress

--vm-stride and CPU us vs sy

3) I/O stress

4) Mixed workload

5) Other handy options

Part 5: Monitoring recommendations

Summary

Key takeaways

Recommendation

References

Docker Feature Overview

Basic Concepts

1) Container

2) Image

3) Registry

How containers, images, and registries relate

Common Commands

Docker Networking

Inspecting Container Details

`--vm-stride` and CPU `us` vs `sy`

`http` vs `server` vs `location`

`include mime.types` and what it means

What `$uri` is (and why it matters for `try_files`)

1) Minimal `upstream` (round-robin by default)

2) Reverse proxy (`proxy_pass`) timeouts