Moving from 1.x

The conclusion first §

• 2.0 cannot be upgraded in place — Pulling a new image is not an in-place upgrade path.
• No data import tool — Reconfigure channels, keys, and Groups in 2.0.
• 1.x is still usable — The maintenance line continues and documentation remains at 1.4.x documentation; if you are not in a hurry, you can stay on it.

What needs to be done is: Start a new 2.0 instance, configure and verify it, then switch traffic. The old set will remain unchanged within the rollback window.

Why 2.0 cannot be upgraded in place §

2.0 rewrites the data model. The fundamental change is the conceptual hierarchy now has two levels: in 1.x, a Group handled both upstream configuration and application authorization; 2.0 separates Group (upstream) from AccessKey (application).

This is not a difference that can be made compatible by adding a few fields—there is no information in the old data to deduce 'which apps should be authorized to use which Groups.' So rather than providing an import tool that might guess wrong, it’s better for you to set it clearly in 2.0. The amount of configuration usually isn't large, and it only needs to be done once.

Concept comparison §

It is easy to confuse the two- and three-layer models; see Core concepts.

Request URL changes §

This is the only required application-side change. 1.x put the Group name in the path; 2.0 does not:

 # 1.x: Address includes Group name 
http://host:3001/proxy/ Your Group name /v1/chat/completions

 # 2.0: Fixed address, which Group to use is determined by AccessKey and model name 
http://host:3001/v1/chat/completions

In other words, in 2.0 the application only needs one base URL and one AccessKey. You can add Groups or change providers in the management UI without touching applications.

Parallel deployment §

The key point is that the four things in the two sets of instances must be completely separated. Sharing any one thing may cause problems:

• Port — Use a new port for 2.0; do not reuse the port used by 1.x.
• Data directory / Docker volume — It must be new; do not reuse the old one.
• Database — Use a new database; even two MySQL deployments need separate databases.
• OAuth Callback Port — Subscription accounts require exclusive callback ports; see Subscription accounts.

 # 1.x Keep running as is, do not touch it 

 # 2.0 clone to another directory 
git clone --depth 1 --branch v2 \
  https://github.com/tbphp/gpt-load.git gpt-load-v2
cd gpt-load-v2
cp .env.example .env

 # Change the port in .env to an unused one, e.g., 3002 
# PORT=3002

docker compose up -d

After startup, use Quick Start to configure: create a Group, add credentials, select models, and issue an AccessKey.

Validation before switching traffic §

Verify each item before moving production traffic:

1. Each Group can run successfully — Send one request with a real model through each Group, not just one.
2. Model names must match — Models are declared per Group in 2.0; verify that the requested model is exposed by the corresponding Group.
3. Protocol Matching — Enable the protocol the application actually uses on its AccessKey.
4. Check monitoring. Confirm the route in Request Logs; see Monitoring and troubleshooting.
5. Go through the production checklist — Pay particular attention to key backups and network boundaries; see Security and production.

It is recommended to switch a non-critical application to 2.0 first and run it for a while, and then switch to the rest after confirming that it is correct.

Rollback §

Because it is deployed in parallel, the rollback means changing the application address and key back to 1.x. There is no data migration that needs to be reversed.