没有不值得去解决的问题,也没有不值得去学习的技术!

The “A Tour of Go” Multilingual Translation Project: Building a Standalone ZgoCloud Execution Proxy for the Playground

Figure 1: TLS handshake timeout when the Alibaba Cloud production environment accesses the go.dev Playground

作者:

在

After the official launch of the Simplified Chinese version of A Tour of Go, I originally thought the code execution part was basically stable.

In the production environment, the course pages are served by an Alibaba Cloud server. When a user clicks “Run” or “Format”, the browser sends the request to the production Go Tour service, which then accesses the official Go Playground API.

The initial execution flow was roughly:

Plaintext
Browser
→ EdgeOne
→ Alibaba Cloud Nginx
→ Go Tour
→ go.dev Playground

This architecture itself had no obvious issues, and the production server does not execute user-submitted Go code locally.

However, after running it for a while, I discovered another problem:

The network connection from the Alibaba Cloud server to the official Go Playground is not always stable.

This ultimately prompted me to separate the code execution traffic from the page service and set up a dedicated US-based execution forwarding node for the Playground.

This article primarily documents how this execution node was set up.

As for how the A Tour of Go frontend switched from the original Alibaba Cloud same-origin API to this new node, and the EdgeOne caching issues encountered during the production rollout, I will cover those in the next article.


1. The Problem Wasn’t Go Code Execution, but the Remote Playground Network Connection

The production environment already had diagnostic logging added for Playground requests.

During an actual failure, the following could be seen:

Plaintext
operation=compile
duration=10.112...
error="Post \"https://go.dev/_/compile\": net/http: TLS handshake timeout"

This means that after waiting for about 10 seconds, the request did not enter a normal Playground compilation response; instead, it failed at the TLS handshake stage.

Figure 1: TLS handshake timeout when the Alibaba Cloud production environment accesses the go.dev Playground
Figure 1: TLS handshake timeout when the Alibaba Cloud production environment accesses the go.dev Playground

A specific clarification is needed here.

This was not a failure of A Tour of Go compiling its own code, nor was it an issue with the Go environment on the Alibaba Cloud server.

The production server does not actually execute user-submitted code at all.

The problem occurred on:

Plaintext
Alibaba Cloud Go Tour
→ go.dev

This public network connection.

Therefore, simply adding more retries on the Go server side or adjusting the timeout could only mitigate the surface symptoms without actually changing the network path.

I preferred to directly move the Playground egress to a location with a more stable connection to the official service.


2. Why Choose the Existing ZgoCloud Server

I already had a US-based ZgoCloud VPS on hand.

This server was already running some long-term network services, with current resources being:

Plaintext
3 CPU
3 GB memory
30 GB storage
1500 GB monthly traffic
200 Mbps bandwidth

Based on historical usage, it only consumes a few dozen GB of traffic per month.

A single Playground compile or format request is essentially just a small amount of Go source code and a JSON response.

Therefore, there was no need to purchase a separate server just for this feature.

A more reasonable approach was:

To add a very lightweight, fixed Playground reverse proxy on the existing ZgoCloud node.

This server was already running:

Plaintext
WireGuard
Wstunnel

So the new Playground service had to meet one important prerequisite:

It must not affect the network services already running stably on the server.


3. First, Compare play.golang.org and go.dev

After deciding on the server, there was another question:

Which official endpoint should the new proxy ultimately connect to?

The original production code used:

Plaintext
https://go.dev/_/compile
https://go.dev/_/fmt

But the Go Playground itself has more direct endpoints:

Plaintext
https://play.golang.org/compile
https://play.golang.org/fmt

So I conducted real compilation request tests on ZgoCloud.

To reduce timing bias from testing one first and then the other, I ultimately used an alternating test method, sending 100 real compile requests to each endpoint.

The results were as follows.

Figure 2: ZgoCloud testing 100 alternating compile requests against play.golang.org and go.dev
Figure 2: ZgoCloud testing 100 alternating compile requests against play.golang.org and go.dev

play.golang.org:

Plaintext
Total requests: 100
HTTP 200: 100/100
Failed requests: 0

Average duration: 0.133 s
Median duration: 0.120 s
P95:      0.254 s
Shortest duration: 0.105 s
Longest duration: 0.286 s

go.dev:

Plaintext
Total requests: 100
HTTP 200: 100/100
Failed requests: 0

Average duration: 0.167 s
Median duration: 0.158 s
P95:      0.267 s
Shortest duration: 0.120 s
Longest duration: 0.545 s

I don’t want to conclude here that:

play.golang.org is always faster than go.dev.

Because in a previous round of testing, the latency difference between the two was actually very small, and go.dev was even slightly faster once for a short period.

A more important conclusion is:

From ZgoCloud, both official endpoints can currently and stably complete real compilation requests.

Since play.golang.org is itself a direct Playground endpoint, I ultimately decided to have the new proxy use:

Plaintext
https://play.golang.org/compile
https://play.golang.org/fmt

This makes the execution flow easier to understand.


4. Continuing to Use OneinStack on ZgoCloud

Because my Alibaba Cloud server had been using OneinStack for a long time, I wanted to keep the Nginx management method as similar as possible on this ZgoCloud server.

However, I did not directly copy the OneinStack directory currently running on Alibaba Cloud this time.

The directory on the production server was already mixed with:

Plaintext
Build artifacts
Installation logs
src cache
Production environment runtime files

Directly copying it was not suitable as an installation source for the new server.

So I restored my previous customizations from a clean OneinStack baseline:

Plaintext
PHP 8.5.9
Imagick 3.8.1

Then, based on the needs of this ZgoCloud setup, I adjusted the OpenSSL used for compiling Nginx to:

Plaintext
OpenSSL 3.5.7

Ultimately, the installation on ZgoCloud resulted in:

Plaintext
nginx/1.31.0
OpenSSL 3.5.7

This server does not need to run WordPress, nor was there any plan to deploy a PHP website.

For me, OneinStack is mostly for:

  • Maintaining a familiar Nginx directory structure;
  • Keeping server operation habits consistent;
  • Making subsequent certificate and virtual host management more convenient.

5. The Trickiest Issue: 443 Was Already Occupied by Existing Network Services

If this were a brand new web server, the Playground proxy could just listen on HTTPS 443.

But this ZgoCloud server was already running Wstunnel:

Plaintext
0.0.0.0:443
→ Wstunnel

WireGuard was using:

Plaintext
UDP 51820

So I couldn’t simply have Nginx also listen on:

Plaintext
443 ssl

Otherwise, it would cause a port conflict with existing services.

I ultimately did not add extra port multiplexing or complex traffic splitting mechanisms just to “use standard 443”, but adopted a simpler solution:

Plaintext
443   → Wstunnel
8443  → Nginx Playground
51820 → WireGuard

The official Playground address was therefore set to:

Plaintext
https://play.go-dev.shuijingwanwq.com:8443

Although this design adds a port number, it has a major advantage:

It does not change the operating architecture of the server’s original network services.

For this low-traffic, fixed-purpose execution API, I believe simplicity, stability, and recoverability are more important than a “prettier-looking URL”.


6. After Fully Initializing OneinStack, Original Network Services Remained Normal

Fully initializing OneinStack is not just about installing Nginx.

It may also involve:

Plaintext
apt package updates
sysctl
limits
rsyslog
SSH service
UFW
System initialization

Since this server was already running WireGuard and Wstunnel, before performing the full initialization, I backed up:

Plaintext
/etc/wireguard/wg0.conf
Wstunnel systemd configuration
Wstunnel TLS certificate and private key
sshd configuration
sysctl configuration
iptables / ip6tables
Routes and rules
Port listening status

I also confirmed that the ZgoCloud console provided VNC and Rescue options for recovery in case of any issues.

Only then did I execute the full OneinStack Nginx installation.

After the successful installation, I performed a real system reboot via the ZgoCloud console.

Ultimately, all three services recovered normally:

Plaintext
nginx:     active
wstunnel:  active
wireguard: active

The ports also completely matched expectations.

Figure 3: Nginx, Wstunnel, and WireGuard services coexisting normally on ZgoCloud, with Playground using port 8443
Figure 3: Nginx, Wstunnel, and WireGuard services coexisting normally on ZgoCloud, with Playground using port 8443

The screenshot shows:

Plaintext
Nginx 1.31.0
OpenSSL 3.5.7

80     → Nginx
443    → Wstunnel
8443   → Nginx
51820  → WireGuard

This step was very important.

It proved that we did not redesign the already stable network environment just to add the Playground service.

The new Nginx Playground service simply joined the existing environment as an additional web service.


7. Issuing an HTTPS Certificate Specifically for the Playground Domain

The domain used by the Playground is:

Plaintext
play.go-dev.shuijingwanwq.com

The DNS resolves directly to ZgoCloud:

Plaintext
154.21.196.249

No CDN was added on top of this.

First, I set up an HTTP virtual host via OneinStack:

Plaintext
/data/wwwroot/play.go-dev.shuijingwanwq.com

HTTP 80 is mainly used for ACME validation.

Because OneinStack’s HTTPS virtual host process listens on 443 by default, and 443 was already in use by an existing service, the certificate was not created through the vhost.sh automatic HTTPS process.

I directly reused acme.sh on the server to issue the Let’s Encrypt certificate via Webroot mode.

The certificate was ultimately installed to:

Plaintext
/usr/local/nginx/conf/ssl/play.go-dev.shuijingwanwq.com.crt
/usr/local/nginx/conf/ssl/play.go-dev.shuijingwanwq.com.key

Then, I separately added for this domain:

Plaintext
8443 ssl

This way:

Plaintext
https://play.go-dev.shuijingwanwq.com:8443

has proper HTTPS.


8. This Proxy Should Not Become an “Open Proxy”

Although the new execution node is just a simple Nginx reverse proxy, I didn’t want it to become a general forwarding gateway where the target address can be arbitrarily specified.

Ultimately, only two precise endpoints were exposed:

Plaintext
/compile
/fmt

They are respectively fixed to forward:

Plaintext
/compile
→ https://play.golang.org/compile

and:

Plaintext
/fmt
→ https://play.golang.org/fmt

The following were not exposed:

Plaintext
/socket
/share
Arbitrary upstream parameters
Arbitrary URL forwarding
Local Go execution

All other paths return:

Plaintext
404

This strictly limits the node’s responsibilities to:

Providing fixed Playground compilation and formatting forwarding capabilities for A Tour of Go.


9. CORS Only Allows the Official A Tour of Go Site

Because the next phase requires the browser to directly make cross-origin requests from:

Plaintext
https://go-dev.shuijingwanwq.com

to:

Plaintext
https://play.go-dev.shuijingwanwq.com:8443

CORS must be handled.

Currently, only the following is allowed:

Plaintext
Origin: https://go-dev.shuijingwanwq.com

It properly supports:

Plaintext
POST
OPTIONS

And this was verified through actual testing:

Plaintext
Correct Origin POST   → 200
OPTIONS               → 204
Wrong Origin          → 403
GET /compile          → 405
Unknown path          → 404

This is more appropriate for this service’s purpose than simply returning:

Plaintext
Access-Control-Allow-Origin: *

It was never meant to be a public Playground API for arbitrary third-party web pages to call, but rather to provide fixed execution forwarding capabilities for the current official site.


10. Also Need to Filter HSTS and Alt-Svc Returned by the Upstream

During debugging, I also encountered a small, easily overlooked issue.

play.golang.org returns:

Plaintext
Strict-Transport-Security
Alt-Svc

If Nginx forwards these response headers as is, the domain the browser sees is actually:

Plaintext
play.go-dev.shuijingwanwq.com:8443

This could cause browser behavior inconsistent with the current deployment method.

Especially HSTS.

The standard 443 port for this domain is not the Playground HTTPS service, but another existing network service on the server.

If the browser later automatically upgrades:

Plaintext
http://play.go-dev.shuijingwanwq.com

to:

Plaintext
https://play.go-dev.shuijingwanwq.com:443

it would not reach our intended Playground service.

Therefore, I explicitly hid the upstream’s:

Plaintext
Strict-Transport-Security
Alt-Svc

This ensures the 8443 API does not propagate HTTPS policies to the browser that are not applicable to the current domain’s deployment method.


11. Final Playground Proxy Acceptance Testing

After completing the Nginx configuration, I conducted a full acceptance test again.

Figure 4: Final acceptance testing of the ZgoCloud Playground proxy
Figure 4: Final acceptance testing of the ZgoCloud Playground proxy

The results were as follows.

/compile:

Plaintext
HTTP 200
ZGOCLOUD_COMPILE_OK

/fmt:

Plaintext
HTTP 200
ZGOCLOUD_FMT_OK

CORS preflight:

Plaintext
HTTP 204

Old paths:

Plaintext
/_/compile
→ HTTP 404

This also means the new public API is officially set to:

Plaintext
https://play.go-dev.shuijingwanwq.com:8443/compile
https://play.go-dev.shuijingwanwq.com:8443/fmt

Instead of continuing to mimic go.dev‘s:

Plaintext
/_/compile
/_/fmt

12. Final Architecture

After completing this phase, the structure of the new Playground node is very simple:

Plaintext
A Tour of Go Browser
        │
        │ HTTPS :8443
        ▼
play.go-dev.shuijingwanwq.com
        │
        │ Nginx fixed reverse proxy
        ▼
play.golang.org

Where:

Plaintext
/compile → play.golang.org/compile
/fmt     → play.golang.org/fmt

The server’s original network services keep their original ports:

Plaintext
443/TCP   → Wstunnel
51820/UDP → WireGuard

The new Playground service uses:

Plaintext
8443/TCP → Nginx

Each service uses a different port, requiring no modifications to the original operating methods.


13. This Phase Only Solved the “Execution Node”

At this point, the entire A Tour of Go Playground migration is not actually complete.

Because the production website’s original JavaScript still requests:

Plaintext
/_/compile
/_/fmt

In other words, even though the new ZgoCloud node is ready, the browser will not automatically use it.

The next phase still requires modifying go-tour-i18n:

Plaintext
Run
→ https://play.go-dev.shuijingwanwq.com:8443/compile

Format
→ https://play.go-dev.shuijingwanwq.com:8443/fmt

And it must be ensured that:

  • The local preview’s SocketTransport is unaffected;
  • Production /socket remains disabled;
  • The old Alibaba Cloud /_/compile and /_/fmt are temporarily kept for compatibility and rollback;
  • The production bundle, auto-deployment scripts, and release manifest are updated synchronously;
  • Finally, it is verified through a real browser, not just server-side curl testing.

During the actual rollout, I encountered a very typical problem:

The new production release was deployed successfully, but the browser was still requesting the old /_/compile.

It turned out that it wasn’t a code or deployment failure, but rather EdgeOne was still caching the old:

Plaintext
/tour/script.js

After refreshing this single resource, the new execution flow took effect immediately.

This part is well suited for a separate article.


Summary

This adjustment initially came about simply because the production environment occasionally experienced:

Plaintext
TLS handshake timeout

But when actually handling it, I didn’t just add more retries on the Alibaba Cloud Go Tour server side. Instead, I split the problem into two independent parts:

Plaintext
Page service
≠
Code execution service

The pages are still served by:

Plaintext
EdgeOne
→ Alibaba Cloud
→ Go Tour

.

Code execution, however, is being migrated to:

Plaintext
Browser
→ ZgoCloud
→ play.golang.org

This approach brings several direct changes:

  • Alibaba Cloud no longer needs to handle the remote forwarding of normal Playground requests;
  • The actual request latency from ZgoCloud to the Playground is currently low and stable in continuous testing;
  • The server’s existing WireGuard and Wstunnel network services did not need to be redesigned;
  • The execution proxy has only two fixed endpoints;
  • The production server still does not execute user-submitted Go code;
  • In the future, if the Playground egress needs to be adjusted, there is no need to change the page service architecture again.

In the next article, I will continue to document:

How to modify the A Tour of Go frontend so that Run / Format truly bypasses Alibaba Cloud and directly accesses ZgoCloud, and why EdgeOne caching caused the old execution flow to temporarily remain in effect during the production rollout.

Once this part is completed, the entire Playground execution flow migration will form a truly closed loop.

关于作者 · 持续学习与技术实践

我是一名拥有 15 年以上开发经验的技术从业者,自 2013 年起持续运营个人技术博客,记录工作与个人项目中遇到的真实问题,以及解决问题过程中的探索、实践和思考。

除了技术写作,我也在持续开发和维护自己的独立项目,探索新技术和新工具在实际场景中的应用。我始终相信,没有不值得去解决的问题,也没有不值得去学习的技术。

如果这篇文章对你有所帮助,欢迎浏览博客中的其他文章,也欢迎交流技术经验与想法。

关于我  ·  GitHub  ·  邮件联系